{"openapi":"3.1.0","info":{"title":"Forge SIS District API","description":"Comprehensive API for Forge SIS district operations. See the Forge SIS Technical Specification v1.0 §9 and §25.","version":"1.0.0","contact":{"name":"Your Resource Consultants","email":"api@forgesis.com"},"license":{"name":"Commercial"}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"apiKey":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{}},"paths":{"/postman.json":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/healthz":{"get":{"summary":"Liveness probe","tags":["Meta"],"description":"Returns service identity and uptime. Does not hit external dependencies — use /readyz for that.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"service":{"type":"string","enum":["forge-sis-api"]},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"uptimeSeconds":{"type":"number"}},"required":["status","service","version","timestamp","uptimeSeconds"],"additionalProperties":false}}}}}}},"/readyz":{"get":{"summary":"Readiness probe","tags":["Meta"],"description":"Actually probes DB and Redis with a per-check 2s timeout. Returns 503 if any hard dependency fails.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"timestamp":{"type":"string","format":"date-time"},"checks":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["ok","fail","skip"]},"latencyMs":{"type":"integer"},"error":{"type":"string"}},"required":["status"],"additionalProperties":false}}},"required":["status","timestamp","checks"],"additionalProperties":false}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"timestamp":{"type":"string","format":"date-time"},"checks":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["ok","fail","skip"]},"latencyMs":{"type":"integer"},"error":{"type":"string"}},"required":["status"],"additionalProperties":false}}},"required":["status","timestamp","checks"],"additionalProperties":false}}}}}}},"/version":{"get":{"summary":"Build metadata","tags":["Meta"],"description":"Returns the git sha, build time, and Node version baked in at container-build time. Used for in-field diagnosis.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"gitSha":{"type":"string"},"buildTime":{"type":"string"},"nodeVersion":{"type":"string"}},"required":["name","version","gitSha","buildTime","nodeVersion"],"additionalProperties":false}}}}}}},"/api/auth/login":{"post":{"summary":"Log in with email + password","tags":["Auth"],"description":"Returns a session cookie on success. Subject to rate limits and account lockout after repeated failures.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subdomain":{"type":"string","minLength":1,"maxLength":63,"pattern":"^[a-z0-9-]+$"},"districtCode":{"type":"string","minLength":1,"maxLength":12},"email":{"type":"string","format":"email","maxLength":200},"password":{"type":"string","minLength":1,"maxLength":200}},"required":["email","password"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"roles":{"type":"array","items":{"type":"string"}},"mfaRequired":{"type":"boolean"}},"required":["id","districtId","email","name","roles","mfaRequired"],"additionalProperties":false},"pendingMfaToken":{"type":"string"}},"required":["user"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/auth/login/mfa-verify":{"post":{"summary":"Complete MFA login with a TOTP code","tags":["Auth"],"description":"Second step of the MFA login flow. Consumes the pendingMfaToken returned by /auth/login and validates the TOTP code. Returns the session cookie on success.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"pendingMfaToken":{"type":"string","minLength":10,"maxLength":128},"totpCode":{"type":"string","minLength":6,"maxLength":8}},"required":["pendingMfaToken","totpCode"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"roles":{"type":"array","items":{"type":"string"}},"mfaRequired":{"type":"boolean"}},"required":["id","districtId","email","name","roles","mfaRequired"],"additionalProperties":false},"pendingMfaToken":{"type":"string"}},"required":["user"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/auth/logout":{"post":{"summary":"Log out (revoke the current session)","tags":["Auth"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"loggedOut":{"type":"boolean","enum":[true]}},"required":["loggedOut"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/auth/session":{"get":{"summary":"Return the current authenticated session, if any","tags":["Auth"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"authenticated":{"type":"boolean"},"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"roles":{"type":"array","items":{"type":"string"}},"permissions":{"type":"array","items":{"type":"string"}}},"required":["id","districtId","personId","email","name","roles","permissions"],"additionalProperties":false,"nullable":true}},"required":["authenticated","user"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/auth/request-password-reset":{"post":{"summary":"Request a password reset email","tags":["Auth"],"description":"Always returns 200 — the response does not reveal whether the email exists.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subdomain":{"type":"string","minLength":1,"maxLength":63,"pattern":"^[a-z0-9-]+$"},"districtCode":{"type":"string","minLength":1,"maxLength":12},"email":{"type":"string","format":"email","maxLength":200}},"required":["email"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/auth/complete-password-reset":{"post":{"summary":"Complete a password reset using an emailed token","tags":["Auth"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subdomain":{"type":"string","minLength":1,"maxLength":63,"pattern":"^[a-z0-9-]+$"},"districtCode":{"type":"string","minLength":1,"maxLength":12},"email":{"type":"string","format":"email","maxLength":200},"token":{"type":"string","minLength":1,"maxLength":200},"password":{"type":"string","minLength":12,"maxLength":200}},"required":["email","token","password"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/auth/complete-invite":{"post":{"summary":"Complete a user invite (set initial password)","tags":["Auth"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subdomain":{"type":"string","minLength":1,"maxLength":63,"pattern":"^[a-z0-9-]+$"},"districtCode":{"type":"string","minLength":1,"maxLength":12},"email":{"type":"string","format":"email","maxLength":200},"token":{"type":"string","minLength":1,"maxLength":200},"password":{"type":"string","minLength":12,"maxLength":200}},"required":["email","token","password"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/auth/saml/metadata":{"get":{"summary":"SAML 2.0 SP metadata","tags":["Auth · SSO"],"description":"Returns SP EntityDescriptor XML for IdP configuration.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"districtId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"string"}}}}}}},"/auth/saml/initiate":{"get":{"summary":"Initiate SAML 2.0 SSO for a district","tags":["Auth · SSO"],"description":"Redirects browser to the district IdP with an encoded AuthnRequest.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"districtId","required":true},{"schema":{"type":"string"},"in":"query","name":"relayState","required":false}],"responses":{"302":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/auth/saml/callback":{"post":{"summary":"SAML 2.0 Assertion Consumer Service (ACS)","tags":["Auth · SSO"],"description":"Receives SAMLResponse from IdP and establishes a Forge session.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"SAMLResponse":{"type":"string","minLength":1},"RelayState":{"type":"string"}},"required":["SAMLResponse"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"redirectTo":{"type":"string"}},"required":["redirectTo"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"302":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}}}}},"/auth/oidc/authorize":{"get":{"summary":"Initiate OIDC SSO for a district","tags":["Auth · SSO"],"description":"Redirects browser to the district OIDC IdP with PKCE parameters.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"districtId","required":true},{"schema":{"type":"string"},"in":"query","name":"redirectTo","required":false}],"responses":{"302":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/auth/oidc/callback":{"get":{"summary":"OIDC authorization code callback","tags":["Auth · SSO"],"description":"Receives authorization code from IdP, exchanges for tokens, creates session.","parameters":[{"schema":{"type":"string"},"in":"query","name":"code","required":false},{"schema":{"type":"string"},"in":"query","name":"state","required":false},{"schema":{"type":"string"},"in":"query","name":"error","required":false},{"schema":{"type":"string"},"in":"query","name":"error_description","required":false}],"responses":{"302":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}}}}},"/auth/classlink/authorize":{"get":{"summary":"Initiate ClassLink SSO for a district","tags":["Auth · SSO"],"description":"Redirects browser to ClassLink IdP for the district tenant.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"districtId","required":true},{"schema":{"type":"string"},"in":"query","name":"redirectTo","required":false}],"responses":{"302":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/auth/classlink/callback":{"get":{"summary":"ClassLink authorization code callback","tags":["Auth · SSO"],"description":"Receives code from ClassLink, exchanges for tokens, creates Forge session.","parameters":[{"schema":{"type":"string"},"in":"query","name":"code","required":false},{"schema":{"type":"string"},"in":"query","name":"state","required":false},{"schema":{"type":"string"},"in":"query","name":"error","required":false}],"responses":{"302":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}}}}},"/district/sso":{"get":{"summary":"Get SSO provider configurations","tags":["District · SSO"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"saml":{"type":"object","properties":{"entityId":{"type":"string"},"ssoUrl":{"type":"string"},"idpEntityId":{"type":"string"},"certificate":{"type":"string"},"nameIdFormat":{"type":"string"}},"required":["entityId","ssoUrl","idpEntityId","certificate","nameIdFormat"],"additionalProperties":false,"nullable":true},"oidc":{"type":"object","properties":{"clientId":{"type":"string"},"clientSecret":{"type":"string"},"discoveryUrl":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["clientId","clientSecret","discoveryUrl","scopes"],"additionalProperties":false,"nullable":true},"classlink":{"type":"object","properties":{"clientId":{"type":"string"},"clientSecret":{"type":"string"},"tenantId":{"type":"string"}},"required":["clientId","clientSecret","tenantId"],"additionalProperties":false,"nullable":true}},"required":["saml","oidc","classlink"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/district/sso/saml":{"post":{"summary":"Save SAML 2.0 configuration","tags":["District · SSO"],"description":"Stores SAML IdP settings in District.settings.sso.saml. No migration required.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"entityId":{"type":"string","format":"uri"},"ssoUrl":{"type":"string","format":"uri"},"idpEntityId":{"type":"string","minLength":1},"certificate":{"type":"string","default":""},"nameIdFormat":{"type":"string"}},"required":["ssoUrl","idpEntityId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/district/sso/oidc":{"post":{"summary":"Save OIDC configuration","tags":["District · SSO"],"description":"Stores OIDC client settings in District.settings.sso.oidc.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"clientId":{"type":"string","minLength":1},"clientSecret":{"type":"string","minLength":1},"discoveryUrl":{"type":"string","format":"uri"},"scopes":{"type":"array","items":{"type":"string"},"default":["openid","email","profile"]}},"required":["clientId","clientSecret","discoveryUrl"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/district/sso/classlink":{"post":{"summary":"Save ClassLink SSO configuration","tags":["District · SSO"],"description":"Stores ClassLink tenant settings in District.settings.sso.classlink.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"clientId":{"type":"string","minLength":1},"clientSecret":{"type":"string","minLength":1},"tenantId":{"type":"string","minLength":1}},"required":["clientId","clientSecret","tenantId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/marketing/plans":{"get":{"summary":"List active pricing tiers for the public /pricing page","tags":["Marketing"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"priceLabel":{"type":"string"},"priceCents":{"type":"integer","nullable":true},"period":{"type":"string","nullable":true},"studentLimit":{"type":"string"},"cta":{"type":"string"},"href":{"type":"string"},"highlight":{"type":"boolean"},"features":{"type":"array","items":{"type":"string"}},"sortOrder":{"type":"integer"}},"required":["id","code","name","description","priceLabel","priceCents","period","studentLimit","cta","href","highlight","features","sortOrder"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/marketing/checkout":{"post":{"summary":"Create a Stripe Checkout Session for a plan","tags":["Marketing"],"description":"Anonymous endpoint that opens a hosted Stripe Checkout flow for a prospect. The webhook handler at /api/platform/v1/webhooks/stripe/billing records the completed checkout for manual district provisioning. Requires STRIPE_PRICE_<UPPERCASE_CODE> env var per plan.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"planCode":{"type":"string","minLength":1,"maxLength":50},"email":{"type":"string","format":"email"},"successUrl":{"type":"string","format":"uri"},"cancelUrl":{"type":"string","format":"uri"}},"required":["planCode","email"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"sessionId":{"type":"string"}},"required":["url","sessionId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/marketing/event-catalog":{"get":{"summary":"Event-type catalog with example payloads","tags":["Marketing"],"description":"Public reference for integrators. Walks the platform event registry and emits one example payload per type so developers can prototype receivers without reading TypeScript schemas.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"version":{"type":"integer"},"description":{"type":"string"},"examplePayload":{}},"required":["type","version","description"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/marketing/content":{"get":{"summary":"Bulk-fetch active marketing copy blocks (optionally by slug list)","tags":["Marketing"],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"in":"query","name":"slug","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"kind":{"type":"string"},"content":{}},"required":["slug","kind"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api-keys/usage-summary":{"get":{"summary":"District-wide API usage rollup for the last 7 days","tags":["API Keys"],"description":"Per-day totals across every active key in the district + per-key totals. Daily totals are summed from the same Redis counters the per-key sparkline uses; per-key totals are the sum of that key's 7-day series.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"integer"}},"required":["date","count"],"additionalProperties":false}},"total":{"type":"integer"},"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"total7d":{"type":"integer"},"lastUsedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","name","keyPrefix","total7d","lastUsedAt"],"additionalProperties":false}}},"required":["daily","total","keys"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api-keys":{"get":{"summary":"List API keys for the current district","tags":["API Keys"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string"},"keyPrefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"ipAllowlist":{"type":"array","items":{"type":"string"},"nullable":true},"rateLimit":{"type":"object","properties":{"requestsPerMinute":{"type":"integer"}},"required":["requestsPerMinute"],"additionalProperties":false,"nullable":true},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"usage7d":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"integer"}},"required":["date","count"],"additionalProperties":false}}},"required":["id","name","type","keyPrefix","scopes","ipAllowlist","rateLimit","lastUsedAt","expiresAt","createdAt","usage7d"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a new API key for the current district","tags":["API Keys"],"description":"Generates a cryptographically random key. The plaintext is returned ONCE in the `key` field and cannot be retrieved again.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"type":{"type":"string","enum":["public","secret","admin","partner"],"default":"secret"},"scopes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100},"ipAllowlist":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":50},"rateLimit":{"type":"object","properties":{"requestsPerMinute":{"type":"integer","minimum":1,"maximum":100000}},"required":["requestsPerMinute"],"additionalProperties":false},"expiresAt":{"type":"string","format":"date-time"}},"required":["name","scopes"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"row":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string"},"keyPrefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"ipAllowlist":{"type":"array","items":{"type":"string"},"nullable":true},"rateLimit":{"type":"object","properties":{"requestsPerMinute":{"type":"integer"}},"required":["requestsPerMinute"],"additionalProperties":false,"nullable":true},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"usage7d":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"integer"}},"required":["date","count"],"additionalProperties":false}}},"required":["id","name","type","keyPrefix","scopes","ipAllowlist","rateLimit","lastUsedAt","expiresAt","createdAt","usage7d"],"additionalProperties":false},"key":{"type":"string","description":"The plaintext key — shown once, never returned again."}},"required":["row","key"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api-keys/{id}":{"delete":{"summary":"Revoke an API key (soft-delete via revokedAt)","tags":["API Keys"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response","content":{"application/json":{"schema":{"enum":["null"],"nullable":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/webhooks":{"get":{"summary":"List webhooks for the current district","tags":["Webhooks"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"description":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","url","events","active","description","createdAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a webhook subscription","tags":["Webhooks"],"description":"Generates a signing secret. The plaintext is returned once in the `signingSecret` field and is never returned again. Use it to verify the `X-Forge-Signature` header on each delivery.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":500},"events":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100},"description":{"type":"string","maxLength":500},"active":{"type":"boolean"}},"required":["url","events"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"row":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"description":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","url","events","active","description","createdAt"],"additionalProperties":false},"signingSecret":{"type":"string","description":"HMAC-SHA256 signing secret. Shown once."}},"required":["row","signingSecret"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/webhooks/{id}":{"delete":{"summary":"Delete (soft) a webhook","tags":["Webhooks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response","content":{"application/json":{"schema":{"enum":["null"],"nullable":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/webhooks/{id}/deliveries":{"get":{"summary":"List recent deliveries for a webhook","tags":["Webhooks"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventId":{"type":"string"},"attempt":{"type":"integer"},"status":{"type":"string"},"responseStatus":{"type":"integer","nullable":true},"scheduledFor":{"type":"string","format":"date-time"},"attemptedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","eventId","attempt","status","responseStatus","scheduledFor","attemptedAt","createdAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/webhooks/{id}/deliveries/{deliveryId}/resend":{"post":{"summary":"Re-enqueue a past delivery (typically a failed one)","tags":["Webhooks"],"description":"Looks up the original event by id and queues a fresh delivery to this webhook. The receiver will see the same payload + eventType as the first attempt; the new attempt gets a new WebhookDelivery row with attempt=N+1.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"deliveryId","required":true}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"},"attempt":{"type":"integer"}},"required":["eventId","attempt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/webhooks/{id}/test":{"post":{"summary":"Fire a synthetic delivery so the operator can verify their receiver","tags":["Webhooks"],"description":"Enqueues a `WebhookTest` event addressed only to this webhook. The receiver gets a normal, signed delivery with eventType=WebhookTest. Useful as a \"ping\" during integration setup.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"}},"required":["eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/webhooks/event-types":{"get":{"summary":"Event types that webhooks can subscribe to","tags":["Webhooks"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/me/push-token":{"post":{"summary":"Register an Expo push token for the signed-in user","tags":["Auth"],"description":"Stores the Expo push token so the backend can send push notifications to this device. Call this once after login. The token is scoped to the district.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":10,"maxLength":200,"pattern":"^ExponentPushToken\\[.+\\]$|^[a-zA-Z0-9_-]{20,}$"},"platform":{"type":"string","enum":["expo","apns","fcm"],"default":"expo"}},"required":["token"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"stored":{"type":"boolean","enum":[true]}},"required":["stored"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Remove the push token for the signed-in user","tags":["Auth"],"description":"Call on logout so the device no longer receives push notifications.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"removed":{"type":"boolean","enum":[true]}},"required":["removed"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/students":{"get":{"summary":"List students","tags":["Students"],"description":"Returns a paginated list of students in the current district.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string"},"in":"query","name":"gradeLevel","required":false},{"schema":{"type":"boolean"},"in":"query","name":"isActive","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"smid":{"type":"string","nullable":true},"localId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"preferredName":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","format":"date","nullable":true},"gradeLevel":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","smid","localId","firstName","lastName","preferredName","dateOfBirth","gradeLevel","isActive"],"additionalProperties":false,"description":"Student record"}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a student","tags":["Students"],"description":"Creates a new student record. Emits StudentEnrolled when paired with an enrollment.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"localId":{"type":"string","minLength":1,"maxLength":50},"dateOfBirth":{"type":"string","format":"date"},"gradeLevel":{"type":"string"},"preferredName":{"type":"string"},"primaryLanguage":{"type":"string","minLength":2,"maxLength":2},"raceEthnicity":{"type":"array","items":{"type":"string"}}},"required":["firstName","lastName","localId"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"smid":{"type":"string","nullable":true},"localId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"preferredName":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","format":"date","nullable":true},"gradeLevel":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","smid","localId","firstName","lastName","preferredName","dateOfBirth","gradeLevel","isActive"],"additionalProperties":false,"description":"Student record"},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/students/{id}":{"get":{"summary":"Get student by ID","tags":["Students"],"description":"Returns a single student record. Caller must have student.read permission.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Student UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"smid":{"type":"string","nullable":true},"localId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"preferredName":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","format":"date","nullable":true},"gradeLevel":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","smid","localId","firstName","lastName","preferredName","dateOfBirth","gradeLevel","isActive"],"additionalProperties":false,"description":"Student record"},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/persons":{"get":{"summary":"List persons (students, guardians, staff, alumni, contacts)","tags":["Persons"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["STUDENT","GUARDIAN","STAFF","ALUMNI","CONTACT"]},"in":"query","name":"personType","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"personType":{"type":"string","enum":["STUDENT","GUARDIAN","STAFF","ALUMNI","CONTACT"]},"localId":{"type":"string"},"smid":{"type":"string","nullable":true},"firstName":{"type":"string"},"middleName":{"type":"string","nullable":true},"lastName":{"type":"string"},"preferredName":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","format":"date","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phoneMobile":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","personType","localId","smid","firstName","middleName","lastName","preferredName","dateOfBirth","email","phoneMobile","isActive"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/persons/{id}":{"get":{"summary":"Get a single person record","tags":["Persons"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"personType":{"type":"string","enum":["STUDENT","GUARDIAN","STAFF","ALUMNI","CONTACT"]},"localId":{"type":"string"},"smid":{"type":"string","nullable":true},"firstName":{"type":"string"},"middleName":{"type":"string","nullable":true},"lastName":{"type":"string"},"preferredName":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","format":"date","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phoneMobile":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","personType","localId","smid","firstName","middleName","lastName","preferredName","dateOfBirth","email","phoneMobile","isActive"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/persons/import":{"post":{"summary":"Bulk CSV import — preview or apply (upserts by localId)","tags":["Persons"],"description":"Upload a CSV of person records. Use `mode=preview` (default) to validate without committing. Use `mode=apply` to upsert all valid rows. Invalid rows are reported per-row and skipped. Upsert key: (districtId, localId).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"csv":{"type":"string","minLength":1,"maxLength":5000000},"mode":{"type":"string","enum":["preview","apply"],"default":"preview"}},"required":["csv"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"valid":{"type":"integer"},"invalid":{"type":"integer"},"created":{"type":"integer"},"updated":{"type":"integer"},"skipped":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"field":{"type":"string"},"message":{"type":"string"}},"required":["row","field","message"],"additionalProperties":false}}},"required":["total","valid","invalid","created","updated","skipped","errors"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/persons/bulk":{"patch":{"summary":"Bulk update persons matching a filter","tags":["Persons"],"description":"Update one or more safe fields on all persons matching the filter. Allowed fields: isActive, email, phoneMobile, phoneHome, gender. PII fields (name, DOB) require individual edits.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"filter":{"type":"object","properties":{"personType":{"type":"string","enum":["STUDENT","GUARDIAN","STAFF","ALUMNI","CONTACT"]},"isActive":{"type":"boolean"},"localIdPrefix":{"type":"string","maxLength":50}},"additionalProperties":false},"updates":{"type":"object","properties":{"isActive":{"type":"boolean"},"email":{"type":"string","format":"email","nullable":true},"phoneMobile":{"type":"string","maxLength":30,"nullable":true},"phoneHome":{"type":"string","maxLength":30,"nullable":true},"gender":{"type":"string","maxLength":20,"nullable":true}},"additionalProperties":false}},"required":["filter","updates"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/persons/duplicates":{"get":{"summary":"Detect potential duplicate person records (fuzzy matching)","tags":["Persons"],"parameters":[{"schema":{"type":"string","enum":["STUDENT","GUARDIAN","STAFF","ALUMNI","CONTACT"]},"in":"query","name":"personType","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"persons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"localId":{"type":"string"},"personType":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"dateOfBirth":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","localId","personType","firstName","lastName","dateOfBirth","email","isActive"],"additionalProperties":false}},"matchReason":{"type":"string"},"confidence":{"type":"string","enum":["high","medium"]}},"required":["persons","matchReason","confidence"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/persons/{id}/merge/{otherId}":{"post":{"summary":"Merge two person records (survivor absorbs the other)","tags":["Persons"],"description":"Re-points FK relations from the absorbed person to the survivor, fills blank fields on the survivor from the absorbed record, then soft-deletes the absorbed person. Student records are not mergeable via API — contact YRC support.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"otherId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"survivorId":{"type":"string","format":"uuid"},"absorbedId":{"type":"string","format":"uuid"}},"required":["survivorId","absorbedId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/guardians":{"get":{"summary":"List guardians","tags":["Guardians"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"localId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email","nullable":true},"phoneMobile":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","localId","firstName","lastName","email","phoneMobile","isActive"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create guardian","tags":["Guardians"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"localId":{"type":"string","minLength":1,"maxLength":50},"firstName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","format":"email"},"phoneMobile":{"type":"string","maxLength":30},"homeLanguages":{"type":"array","items":{"type":"string"}}},"required":["localId","firstName","lastName"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"localId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email","nullable":true},"phoneMobile":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","localId","firstName","lastName","email","phoneMobile","isActive"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/guardians/{id}":{"get":{"summary":"Get guardian","tags":["Guardians"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"localId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email","nullable":true},"phoneMobile":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","localId","firstName","lastName","email","phoneMobile","isActive"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/guardians/{id}/students":{"get":{"summary":"List students linked to this guardian","tags":["Guardians"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"guardianshipId":{"type":"string","format":"uuid"},"studentId":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"relationshipType":{"type":"string"},"hasCustody":{"type":"boolean"},"emergencyContactPriority":{"type":"integer"}},"required":["guardianshipId","studentId","firstName","lastName","relationshipType","hasCustody","emergencyContactPriority"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Link a guardian to a student (emits GuardianLinked)","tags":["Guardians"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"relationshipType":{"type":"string","enum":["mother","father","grandparent","legal_guardian","stepparent","other"]},"hasCustody":{"type":"boolean","default":true},"livesWithStudent":{"type":"boolean","default":true},"canPickup":{"type":"boolean","default":true},"canReceiveComms":{"type":"boolean","default":true},"canAccessRecords":{"type":"boolean","default":true},"emergencyContactPriority":{"type":"integer","minimum":1,"maximum":99,"default":99},"startDate":{"type":"string","format":"date"}},"required":["studentId","relationshipType","startDate"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"guardianshipId":{"type":"string","format":"uuid"},"eventId":{"type":"string","format":"uuid"}},"required":["guardianshipId","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/guardianships/{id}":{"delete":{"summary":"Unlink a guardianship (emits GuardianUnlinked)","tags":["Guardians"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":300}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"}},"required":["eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/students/{studentId}/custody-orders":{"get":{"summary":"List custody orders for a student","tags":["Custody"],"parameters":[{"schema":{"type":"boolean","default":false},"in":"query","name":"includeRevoked","required":false},{"schema":{"type":"boolean","default":false},"in":"query","name":"includeExpired","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"studentId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentId":{"type":"string","format":"uuid"},"restrictedPersonId":{"type":"string","format":"uuid","nullable":true},"orderType":{"type":"string"},"issuingCourt":{"type":"string","nullable":true},"caseNumber":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true},"effectiveDate":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"noPickup":{"type":"boolean"},"noContactAtSchool":{"type":"boolean"},"noReceiveComms":{"type":"boolean"},"noAccessRecords":{"type":"boolean"},"notes":{"type":"string","nullable":true},"recordedByUserId":{"type":"string","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"revokedReason":{"type":"string","nullable":true},"isExpired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","studentId","restrictedPersonId","orderType","issuingCourt","caseNumber","documentUrl","effectiveDate","expiresAt","noPickup","noContactAtSchool","noReceiveComms","noAccessRecords","notes","recordedByUserId","revokedAt","revokedReason","isExpired","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Record a new custody order for a student","tags":["Custody"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"restrictedPersonId":{"type":"string","format":"uuid","nullable":true},"orderType":{"type":"string","enum":["no_contact","restricted_pickup","supervised_visitation","primary_custody","joint_custody","other"]},"issuingCourt":{"type":"string","maxLength":200,"nullable":true},"caseNumber":{"type":"string","maxLength":100,"nullable":true},"documentUrl":{"type":"string","format":"uri","maxLength":2000,"nullable":true},"effectiveDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"noPickup":{"type":"boolean","default":false},"noContactAtSchool":{"type":"boolean","default":false},"noReceiveComms":{"type":"boolean","default":false},"noAccessRecords":{"type":"boolean","default":false},"notes":{"type":"string","maxLength":5000,"nullable":true}},"required":["studentId","orderType","effectiveDate"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"studentId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentId":{"type":"string","format":"uuid"},"restrictedPersonId":{"type":"string","format":"uuid","nullable":true},"orderType":{"type":"string"},"issuingCourt":{"type":"string","nullable":true},"caseNumber":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true},"effectiveDate":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"noPickup":{"type":"boolean"},"noContactAtSchool":{"type":"boolean"},"noReceiveComms":{"type":"boolean"},"noAccessRecords":{"type":"boolean"},"notes":{"type":"string","nullable":true},"recordedByUserId":{"type":"string","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"revokedReason":{"type":"string","nullable":true},"isExpired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","studentId","restrictedPersonId","orderType","issuingCourt","caseNumber","documentUrl","effectiveDate","expiresAt","noPickup","noContactAtSchool","noReceiveComms","noAccessRecords","notes","recordedByUserId","revokedAt","revokedReason","isExpired","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/custody-orders/{id}":{"get":{"summary":"Get a single custody order by ID","tags":["Custody"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentId":{"type":"string","format":"uuid"},"restrictedPersonId":{"type":"string","format":"uuid","nullable":true},"orderType":{"type":"string"},"issuingCourt":{"type":"string","nullable":true},"caseNumber":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true},"effectiveDate":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"noPickup":{"type":"boolean"},"noContactAtSchool":{"type":"boolean"},"noReceiveComms":{"type":"boolean"},"noAccessRecords":{"type":"boolean"},"notes":{"type":"string","nullable":true},"recordedByUserId":{"type":"string","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"revokedReason":{"type":"string","nullable":true},"isExpired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","studentId","restrictedPersonId","orderType","issuingCourt","caseNumber","documentUrl","effectiveDate","expiresAt","noPickup","noContactAtSchool","noReceiveComms","noAccessRecords","notes","recordedByUserId","revokedAt","revokedReason","isExpired","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update custody order metadata","tags":["Custody"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"issuingCourt":{"type":"string","maxLength":200,"nullable":true},"caseNumber":{"type":"string","maxLength":100,"nullable":true},"documentUrl":{"type":"string","format":"uri","maxLength":2000,"nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"noPickup":{"type":"boolean"},"noContactAtSchool":{"type":"boolean"},"noReceiveComms":{"type":"boolean"},"noAccessRecords":{"type":"boolean"},"notes":{"type":"string","maxLength":5000,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentId":{"type":"string","format":"uuid"},"restrictedPersonId":{"type":"string","format":"uuid","nullable":true},"orderType":{"type":"string"},"issuingCourt":{"type":"string","nullable":true},"caseNumber":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true},"effectiveDate":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"noPickup":{"type":"boolean"},"noContactAtSchool":{"type":"boolean"},"noReceiveComms":{"type":"boolean"},"noAccessRecords":{"type":"boolean"},"notes":{"type":"string","nullable":true},"recordedByUserId":{"type":"string","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"revokedReason":{"type":"string","nullable":true},"isExpired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","studentId","restrictedPersonId","orderType","issuingCourt","caseNumber","documentUrl","effectiveDate","expiresAt","noPickup","noContactAtSchool","noReceiveComms","noAccessRecords","notes","recordedByUserId","revokedAt","revokedReason","isExpired","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/custody-orders/{id}/revoke":{"post":{"summary":"Revoke a custody order (soft-expire with reason)","tags":["Custody"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentId":{"type":"string","format":"uuid"},"restrictedPersonId":{"type":"string","format":"uuid","nullable":true},"orderType":{"type":"string"},"issuingCourt":{"type":"string","nullable":true},"caseNumber":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true},"effectiveDate":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"noPickup":{"type":"boolean"},"noContactAtSchool":{"type":"boolean"},"noReceiveComms":{"type":"boolean"},"noAccessRecords":{"type":"boolean"},"notes":{"type":"string","nullable":true},"recordedByUserId":{"type":"string","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"revokedReason":{"type":"string","nullable":true},"isExpired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","studentId","restrictedPersonId","orderType","issuingCourt","caseNumber","documentUrl","effectiveDate","expiresAt","noPickup","noContactAtSchool","noReceiveComms","noAccessRecords","notes","recordedByUserId","revokedAt","revokedReason","isExpired","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/students/{studentId}/pickup-authorized":{"get":{"summary":"Check pickup authorization for a person + student pair","tags":["Custody"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"personId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"studentId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"authorized":{"type":"boolean"},"reason":{"type":"string"},"guardianship":{"type":"object","properties":{"hasCustody":{"type":"boolean"},"canPickup":{"type":"boolean"},"relationshipType":{"type":"string"}},"required":["hasCustody","canPickup","relationshipType"],"additionalProperties":false,"nullable":true},"blockingOrders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderType":{"type":"string"},"noPickup":{"type":"boolean"},"noContactAtSchool":{"type":"boolean"}},"required":["id","orderType","noPickup","noContactAtSchool"],"additionalProperties":false}}},"required":["authorized","reason","guardianship","blockingOrders"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/staff":{"get":{"summary":"List staff (and faculty) records","tags":["Staff"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"localId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email","nullable":true},"phoneMobile":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","localId","firstName","lastName","email","phoneMobile","isActive"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a staff record","tags":["Staff"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"localId":{"type":"string","minLength":1,"maxLength":50},"firstName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","format":"email"},"phoneMobile":{"type":"string","maxLength":30}},"required":["localId","firstName","lastName"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"localId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email","nullable":true},"phoneMobile":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","localId","firstName","lastName","email","phoneMobile","isActive"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/staff/{id}":{"get":{"summary":"Get a staff record","tags":["Staff"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"localId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email","nullable":true},"phoneMobile":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","localId","firstName","lastName","email","phoneMobile","isActive"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/enrollments":{"get":{"summary":"List enrollments (filter by person, organization, or active-only)","tags":["Enrollments"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"personId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"organizationId","required":false},{"schema":{"type":"boolean"},"in":"query","name":"active","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"enrollmentType":{"type":"string","enum":["STUDENT","STAFF","FACULTY","VOLUNTEER","CONTRACTOR"]},"role":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"exitReason":{"type":"string","nullable":true},"exitCode":{"type":"string","nullable":true},"isPrimary":{"type":"boolean"}},"required":["id","districtId","personId","organizationId","enrollmentType","role","gradeLevel","startDate","endDate","exitReason","exitCode","isPrimary"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create an enrollment (emits StudentEnrolled for students)","tags":["Enrollments"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"enrollmentType":{"type":"string","enum":["STUDENT","STAFF","FACULTY","VOLUNTEER","CONTRACTOR"]},"role":{"type":"string","minLength":1,"maxLength":50},"gradeLevel":{"type":"string","maxLength":5},"startDate":{"type":"string","format":"date"},"isPrimary":{"type":"boolean","default":true}},"required":["personId","organizationId","enrollmentType","role","startDate"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"enrollment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"enrollmentType":{"type":"string","enum":["STUDENT","STAFF","FACULTY","VOLUNTEER","CONTRACTOR"]},"role":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"exitReason":{"type":"string","nullable":true},"exitCode":{"type":"string","nullable":true},"isPrimary":{"type":"boolean"}},"required":["id","districtId","personId","organizationId","enrollmentType","role","gradeLevel","startDate","endDate","exitReason","exitCode","isPrimary"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["enrollment","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/enrollments/{id}":{"get":{"summary":"Get a single enrollment","tags":["Enrollments"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"enrollmentType":{"type":"string","enum":["STUDENT","STAFF","FACULTY","VOLUNTEER","CONTRACTOR"]},"role":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"exitReason":{"type":"string","nullable":true},"exitCode":{"type":"string","nullable":true},"isPrimary":{"type":"boolean"}},"required":["id","districtId","personId","organizationId","enrollmentType","role","gradeLevel","startDate","endDate","exitReason","exitCode","isPrimary"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/enrollments/{id}/end":{"post":{"summary":"End an enrollment (emits StudentWithdrawn for students)","tags":["Enrollments"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"endDate":{"type":"string","format":"date"},"exitReason":{"type":"string","maxLength":100},"exitCode":{"type":"string","maxLength":10}},"required":["endDate","exitReason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"enrollment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"enrollmentType":{"type":"string","enum":["STUDENT","STAFF","FACULTY","VOLUNTEER","CONTRACTOR"]},"role":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"exitReason":{"type":"string","nullable":true},"exitCode":{"type":"string","nullable":true},"isPrimary":{"type":"boolean"}},"required":["id","districtId","personId","organizationId","enrollmentType","role","gradeLevel","startDate","endDate","exitReason","exitCode","isPrimary"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["enrollment","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/organizations":{"get":{"summary":"List organizations (school, department, grade, homeroom, program)","tags":["Scheduling"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["SCHOOL","DEPARTMENT","GRADE_LEVEL","HOMEROOM","PROGRAM"]},"in":"query","name":"type","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"parentOrgId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"parentOrgId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string","enum":["SCHOOL","DEPARTMENT","GRADE_LEVEL","HOMEROOM","PROGRAM"]},"code":{"type":"string"},"name":{"type":"string"},"shortName":{"type":"string","nullable":true},"stateCode":{"type":"string","nullable":true},"gradeRangeLow":{"type":"string","nullable":true},"gradeRangeHigh":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","parentOrgId","type","code","name","shortName","stateCode","gradeRangeLow","gradeRangeHigh","isActive"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create an organization","tags":["Scheduling"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"parentOrgId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["SCHOOL","DEPARTMENT","GRADE_LEVEL","HOMEROOM","PROGRAM"]},"code":{"type":"string","minLength":1,"maxLength":20},"name":{"type":"string","minLength":1,"maxLength":200},"shortName":{"type":"string","maxLength":50},"stateCode":{"type":"string","maxLength":20},"gradeRangeLow":{"type":"string","maxLength":5},"gradeRangeHigh":{"type":"string","maxLength":5}},"required":["type","code","name"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"parentOrgId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string","enum":["SCHOOL","DEPARTMENT","GRADE_LEVEL","HOMEROOM","PROGRAM"]},"code":{"type":"string"},"name":{"type":"string"},"shortName":{"type":"string","nullable":true},"stateCode":{"type":"string","nullable":true},"gradeRangeLow":{"type":"string","nullable":true},"gradeRangeHigh":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","parentOrgId","type","code","name","shortName","stateCode","gradeRangeLow","gradeRangeHigh","isActive"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/organizations/{id}":{"get":{"summary":"Get an organization","tags":["Scheduling"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"parentOrgId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string","enum":["SCHOOL","DEPARTMENT","GRADE_LEVEL","HOMEROOM","PROGRAM"]},"code":{"type":"string"},"name":{"type":"string"},"shortName":{"type":"string","nullable":true},"stateCode":{"type":"string","nullable":true},"gradeRangeLow":{"type":"string","nullable":true},"gradeRangeHigh":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","parentOrgId","type","code","name","shortName","stateCode","gradeRangeLow","gradeRangeHigh","isActive"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update organization","tags":["Scheduling"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"parentOrgId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["SCHOOL","DEPARTMENT","GRADE_LEVEL","HOMEROOM","PROGRAM"]},"code":{"type":"string","minLength":1,"maxLength":20},"name":{"type":"string","minLength":1,"maxLength":200},"shortName":{"type":"string","maxLength":50},"stateCode":{"type":"string","maxLength":20},"gradeRangeLow":{"type":"string","maxLength":5},"gradeRangeHigh":{"type":"string","maxLength":5}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"parentOrgId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string","enum":["SCHOOL","DEPARTMENT","GRADE_LEVEL","HOMEROOM","PROGRAM"]},"code":{"type":"string"},"name":{"type":"string"},"shortName":{"type":"string","nullable":true},"stateCode":{"type":"string","nullable":true},"gradeRangeLow":{"type":"string","nullable":true},"gradeRangeHigh":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","districtId","parentOrgId","type","code","name","shortName","stateCode","gradeRangeLow","gradeRangeHigh","isActive"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/schools":{"get":{"summary":"List schools in the current district","tags":["Scheduling"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"code":{"type":"string"},"principal":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"gradeRangeLow":{"type":"string","nullable":true},"gradeRangeHigh":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string","maxLength":10}},"additionalProperties":false},"bellSchedule":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"start":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"end":{"type":"string","pattern":"^\\d{2}:\\d{2}$"}},"required":["name","start","end"],"additionalProperties":false},"default":[]}},"additionalProperties":false}},"required":["id","districtId","organizationId","name","code","principal","phone","website","gradeRangeLow","gradeRangeHigh","address","bellSchedule"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a school (also creates its backing Organization row)","tags":["Scheduling"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":20},"name":{"type":"string","minLength":1,"maxLength":200},"shortName":{"type":"string","maxLength":50},"principal":{"type":"string","maxLength":200},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string","maxLength":10}},"additionalProperties":false,"default":{}},"phone":{"type":"string","maxLength":30},"website":{"type":"string","format":"uri"},"gradeRangeLow":{"type":"string","maxLength":5},"gradeRangeHigh":{"type":"string","maxLength":5},"bellSchedule":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"start":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"end":{"type":"string","pattern":"^\\d{2}:\\d{2}$"}},"required":["name","start","end"],"additionalProperties":false},"default":[]}},"additionalProperties":false,"default":{"periods":[]}}},"required":["code","name"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"code":{"type":"string"},"principal":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"gradeRangeLow":{"type":"string","nullable":true},"gradeRangeHigh":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string","maxLength":10}},"additionalProperties":false},"bellSchedule":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"start":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"end":{"type":"string","pattern":"^\\d{2}:\\d{2}$"}},"required":["name","start","end"],"additionalProperties":false},"default":[]}},"additionalProperties":false}},"required":["id","districtId","organizationId","name","code","principal","phone","website","gradeRangeLow","gradeRangeHigh","address","bellSchedule"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/schools/{id}":{"get":{"summary":"Get a school","tags":["Scheduling"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"code":{"type":"string"},"principal":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"gradeRangeLow":{"type":"string","nullable":true},"gradeRangeHigh":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string","maxLength":10}},"additionalProperties":false},"bellSchedule":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"start":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"end":{"type":"string","pattern":"^\\d{2}:\\d{2}$"}},"required":["name","start","end"],"additionalProperties":false},"default":[]}},"additionalProperties":false}},"required":["id","districtId","organizationId","name","code","principal","phone","website","gradeRangeLow","gradeRangeHigh","address","bellSchedule"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a school","tags":["Scheduling"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":20},"name":{"type":"string","minLength":1,"maxLength":200},"shortName":{"type":"string","maxLength":50},"principal":{"type":"string","maxLength":200},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string","maxLength":10}},"additionalProperties":false,"default":{}},"phone":{"type":"string","maxLength":30},"website":{"type":"string","format":"uri"},"gradeRangeLow":{"type":"string","maxLength":5},"gradeRangeHigh":{"type":"string","maxLength":5},"bellSchedule":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"start":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"end":{"type":"string","pattern":"^\\d{2}:\\d{2}$"}},"required":["name","start","end"],"additionalProperties":false},"default":[]}},"additionalProperties":false,"default":{"periods":[]}}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"code":{"type":"string"},"principal":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"gradeRangeLow":{"type":"string","nullable":true},"gradeRangeHigh":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string","maxLength":10}},"additionalProperties":false},"bellSchedule":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"start":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"end":{"type":"string","pattern":"^\\d{2}:\\d{2}$"}},"required":["name","start","end"],"additionalProperties":false},"default":[]}},"additionalProperties":false}},"required":["id","districtId","organizationId","name","code","principal","phone","website","gradeRangeLow","gradeRangeHigh","address","bellSchedule"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/admin/users":{"get":{"summary":"List district users","tags":["Admin"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string","enum":["active","invited","disabled"]},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"status":{"type":"string"},"personId":{"type":"string","format":"uuid"},"emailVerified":{"type":"boolean"},"mfaEnabled":{"type":"boolean"},"lastLoginAt":{"type":"string","format":"date-time","nullable":true},"roles":{"type":"array","items":{"type":"object","properties":{"roleId":{"type":"string","format":"uuid"},"code":{"type":"string"},"scope":{"type":"object","additionalProperties":{}}},"required":["roleId","code","scope"],"additionalProperties":false}}},"required":["id","districtId","email","name","status","personId","emailVerified","mfaEnabled","lastLoginAt","roles"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/admin/users/{id}":{"get":{"summary":"Get a single user","tags":["Admin"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"status":{"type":"string"},"personId":{"type":"string","format":"uuid"},"emailVerified":{"type":"boolean"},"mfaEnabled":{"type":"boolean"},"lastLoginAt":{"type":"string","format":"date-time","nullable":true},"roles":{"type":"array","items":{"type":"object","properties":{"roleId":{"type":"string","format":"uuid"},"code":{"type":"string"},"scope":{"type":"object","additionalProperties":{}}},"required":["roleId","code","scope"],"additionalProperties":false}}},"required":["id","districtId","email","name","status","personId","emailVerified","mfaEnabled","lastLoginAt","roles"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/admin/users/invite":{"post":{"summary":"Invite a new user (creates User row + issues invite token)","tags":["Admin"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":200},"personId":{"type":"string","format":"uuid"},"sendEmail":{"type":"boolean","default":true},"mfaRequired":{"type":"boolean","default":false},"welcomeNote":{"type":"string","maxLength":500}},"required":["email","personId"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"userId":{"type":"string","format":"uuid"},"inviteToken":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["userId","inviteToken","expiresAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/admin/users/{id}/status":{"post":{"summary":"Set a user status (active / disabled)","tags":["Admin"],"description":"Disabling a user revokes all their active sessions.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","disabled"]},"reason":{"type":"string","maxLength":500}},"required":["status"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"status":{"type":"string"},"personId":{"type":"string","format":"uuid"},"emailVerified":{"type":"boolean"},"mfaEnabled":{"type":"boolean"},"lastLoginAt":{"type":"string","format":"date-time","nullable":true},"roles":{"type":"array","items":{"type":"object","properties":{"roleId":{"type":"string","format":"uuid"},"code":{"type":"string"},"scope":{"type":"object","additionalProperties":{}}},"required":["roleId","code","scope"],"additionalProperties":false}}},"required":["id","districtId","email","name","status","personId","emailVerified","mfaEnabled","lastLoginAt","roles"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/admin/users/{id}/send-password-reset":{"post":{"summary":"Issue a password-reset token for a user (admin action)","tags":["Admin"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["token","expiresAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/admin/users/{id}/roles":{"post":{"summary":"Assign a role (district- or school-scoped) to a user","tags":["Admin"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"roleCode":{"type":"string"},"scope":{"type":"object","properties":{"level":{"type":"string","enum":["district","school"]},"schoolId":{"type":"string","format":"uuid"}},"required":["level"],"additionalProperties":false,"description":"Role scope — district-wide or bound to a specific school"}},"required":["roleCode","scope"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"userRoleId":{"type":"string","format":"uuid"}},"required":["userRoleId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/admin/users/{id}/roles/{userRoleId}":{"delete":{"summary":"Revoke a role binding from a user","tags":["Admin"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"userRoleId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revoked":{"type":"boolean","enum":[true]}},"required":["revoked"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/admin/roles":{"get":{"summary":"List the canonical role catalog","tags":["Admin"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true}},"required":["id","code","name","description"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/attendance":{"post":{"summary":"Bulk mark attendance","tags":["Attendance"],"description":"Each mark produces one AttendanceMarked event; projections are rebuilt asynchronously.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"marks":{"type":"array","items":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"sectionId":{"type":"string","format":"uuid"},"period":{"type":"string","maxLength":10},"date":{"type":"string","format":"date"},"status":{"type":"string","enum":["present","absent","tardy","excused","half_day","iss","oss","remote"]},"code":{"type":"string","minLength":1,"maxLength":10}},"required":["studentId","date","status","code"],"additionalProperties":false},"minItems":1,"maxItems":500}},"required":["marks"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"accepted":{"type":"integer"},"eventIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["accepted","eventIds"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"get":{"summary":"Query attendance days (projection)","tags":["Attendance"],"description":"Reads from projection_attendance_days. Projection is eventually consistent — fresh writes may take a few seconds to reflect.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"districtId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date"},"status":{"type":"string"},"code":{"type":"string"},"periodBreakdown":{"type":"object","additionalProperties":{}},"lastEventId":{"type":"string"}},"required":["districtId","studentPersonId","schoolId","date","status","code","periodBreakdown","lastEventId"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/events":{"get":{"summary":"Query the event log","tags":["Events"],"description":"Filter by eventType, subjectId, actorId, and time range. The event log is append-only (spec §4 rule 7, §8).","parameters":[{"schema":{"type":"string"},"in":"query","name":"eventType","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"subjectId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"actorId","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"to","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"eventVersion":{"type":"integer"},"actorId":{"type":"string","format":"uuid","nullable":true},"actorType":{"type":"string","nullable":true},"subjectId":{"type":"string","format":"uuid","nullable":true},"subjectType":{"type":"string","nullable":true},"occurredAt":{"type":"string","format":"date-time"},"recordedAt":{"type":"string","format":"date-time"},"payload":{"type":"object","additionalProperties":{}},"metadata":{"type":"object","additionalProperties":{},"nullable":true},"correlationId":{"type":"string","nullable":true},"causationId":{"type":"string","nullable":true}},"required":["id","districtId","eventType","eventVersion","actorId","actorType","subjectId","subjectType","occurredAt","recordedAt","payload","metadata","correlationId","causationId"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/events/{id}":{"get":{"summary":"Get a single event by id","tags":["Events"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"eventVersion":{"type":"integer"},"actorId":{"type":"string","format":"uuid","nullable":true},"actorType":{"type":"string","nullable":true},"subjectId":{"type":"string","format":"uuid","nullable":true},"subjectType":{"type":"string","nullable":true},"occurredAt":{"type":"string","format":"date-time"},"recordedAt":{"type":"string","format":"date-time"},"payload":{"type":"object","additionalProperties":{}},"metadata":{"type":"object","additionalProperties":{},"nullable":true},"correlationId":{"type":"string","nullable":true},"causationId":{"type":"string","nullable":true}},"required":["id","districtId","eventType","eventVersion","actorId","actorType","subjectId","subjectType","occurredAt","recordedAt","payload","metadata","correlationId","causationId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/students/{id}/events":{"get":{"summary":"Get a student's event history (audit trail)","tags":["Students","Events"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"eventType","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"to","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"eventVersion":{"type":"integer"},"actorId":{"type":"string","format":"uuid","nullable":true},"actorType":{"type":"string","nullable":true},"subjectId":{"type":"string","format":"uuid","nullable":true},"subjectType":{"type":"string","nullable":true},"occurredAt":{"type":"string","format":"date-time"},"recordedAt":{"type":"string","format":"date-time"},"payload":{"type":"object","additionalProperties":{}},"metadata":{"type":"object","additionalProperties":{},"nullable":true},"correlationId":{"type":"string","nullable":true},"causationId":{"type":"string","nullable":true}},"required":["id","districtId","eventType","eventVersion","actorId","actorType","subjectId","subjectType","occurredAt","recordedAt","payload","metadata","correlationId","causationId"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/audit-log":{"get":{"summary":"Query the district audit log","tags":["Compliance"],"description":"Security-sensitive audit log (spec §4 rule 7). Distinct from the business event log at /events.","parameters":[{"schema":{"type":"string"},"in":"query","name":"action","required":false},{"schema":{"type":"string"},"in":"query","name":"resource","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"actorId","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"to","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"actorId":{"type":"string","format":"uuid","nullable":true},"actorType":{"type":"string"},"action":{"type":"string"},"resource":{"type":"string"},"resourceId":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":{}},"ipAddress":{"type":"string","nullable":true},"userAgent":{"type":"string","nullable":true},"occurredAt":{"type":"string","format":"date-time"}},"required":["id","districtId","actorId","actorType","action","resource","resourceId","metadata","ipAddress","userAgent","occurredAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/school-years":{"get":{"summary":"List school years","tags":["Scheduling"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"name":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"isCurrent":{"type":"boolean"}},"required":["id","districtId","name","startDate","endDate","isCurrent"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a school year","tags":["Scheduling"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":4,"maxLength":50},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"isCurrent":{"type":"boolean","default":false}},"required":["name","startDate","endDate"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"name":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"isCurrent":{"type":"boolean"}},"required":["id","districtId","name","startDate","endDate","isCurrent"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/school-years/current":{"get":{"summary":"Get the active school year for this district","tags":["Scheduling"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"name":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"isCurrent":{"type":"boolean"}},"required":["id","districtId","name","startDate","endDate","isCurrent"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/school-years/{id}":{"get":{"summary":"Get school year","tags":["Scheduling"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"name":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"isCurrent":{"type":"boolean"}},"required":["id","districtId","name","startDate","endDate","isCurrent"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update school year","tags":["Scheduling"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":4,"maxLength":50},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"isCurrent":{"type":"boolean","default":false}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"name":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"isCurrent":{"type":"boolean"}},"required":["id","districtId","name","startDate","endDate","isCurrent"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/school-years/{id}/actions/set-current":{"post":{"summary":"Mark a school year as current (clears the flag on others)","tags":["Scheduling"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"name":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"isCurrent":{"type":"boolean"}},"required":["id","districtId","name","startDate","endDate","isCurrent"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/terms":{"get":{"summary":"List terms (optionally filter by school year or type)","tags":["Scheduling"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":false},{"schema":{"type":"string","enum":["YEAR","SEMESTER","TRIMESTER","QUARTER","MARKING_PERIOD","PROGRESS_PERIOD"]},"in":"query","name":"termType","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"termType":{"type":"string","enum":["YEAR","SEMESTER","TRIMESTER","QUARTER","MARKING_PERIOD","PROGRESS_PERIOD"]},"name":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"gradingStartDate":{"type":"string","format":"date","nullable":true},"gradingEndDate":{"type":"string","format":"date","nullable":true},"isGradingPeriod":{"type":"boolean"}},"required":["id","districtId","schoolYearId","termType","name","startDate","endDate","gradingStartDate","gradingEndDate","isGradingPeriod"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a term","tags":["Scheduling"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"termType":{"type":"string","enum":["YEAR","SEMESTER","TRIMESTER","QUARTER","MARKING_PERIOD","PROGRESS_PERIOD"]},"name":{"type":"string","minLength":1,"maxLength":100},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"gradingStartDate":{"type":"string","format":"date"},"gradingEndDate":{"type":"string","format":"date"},"isGradingPeriod":{"type":"boolean","default":false}},"required":["schoolYearId","termType","name","startDate","endDate"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"termType":{"type":"string","enum":["YEAR","SEMESTER","TRIMESTER","QUARTER","MARKING_PERIOD","PROGRESS_PERIOD"]},"name":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"gradingStartDate":{"type":"string","format":"date","nullable":true},"gradingEndDate":{"type":"string","format":"date","nullable":true},"isGradingPeriod":{"type":"boolean"}},"required":["id","districtId","schoolYearId","termType","name","startDate","endDate","gradingStartDate","gradingEndDate","isGradingPeriod"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/terms/{id}":{"get":{"summary":"Get a term","tags":["Scheduling"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"termType":{"type":"string","enum":["YEAR","SEMESTER","TRIMESTER","QUARTER","MARKING_PERIOD","PROGRESS_PERIOD"]},"name":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"gradingStartDate":{"type":"string","format":"date","nullable":true},"gradingEndDate":{"type":"string","format":"date","nullable":true},"isGradingPeriod":{"type":"boolean"}},"required":["id","districtId","schoolYearId","termType","name","startDate","endDate","gradingStartDate","gradingEndDate","isGradingPeriod"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a term","tags":["Scheduling"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"termType":{"type":"string","enum":["YEAR","SEMESTER","TRIMESTER","QUARTER","MARKING_PERIOD","PROGRESS_PERIOD"]},"name":{"type":"string","minLength":1,"maxLength":100},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"gradingStartDate":{"type":"string","format":"date"},"gradingEndDate":{"type":"string","format":"date"},"isGradingPeriod":{"type":"boolean","default":false}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"termType":{"type":"string","enum":["YEAR","SEMESTER","TRIMESTER","QUARTER","MARKING_PERIOD","PROGRESS_PERIOD"]},"name":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"gradingStartDate":{"type":"string","format":"date","nullable":true},"gradingEndDate":{"type":"string","format":"date","nullable":true},"isGradingPeriod":{"type":"boolean"}},"required":["id","districtId","schoolYearId","termType","name","startDate","endDate","gradingStartDate","gradingEndDate","isGradingPeriod"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/courses":{"get":{"summary":"List courses in the catalog","tags":["Courses"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string"},"in":"query","name":"subjectArea","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"courseCode":{"type":"string"},"name":{"type":"string"},"shortName":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"stateCourseCode":{"type":"string","nullable":true},"credits":{"type":"number","nullable":true},"gradeLevels":{"type":"array","items":{"type":"string"}},"subjectArea":{"type":"string"},"department":{"type":"string","nullable":true},"isHonors":{"type":"boolean"},"isAP":{"type":"boolean"},"isDualEnrollment":{"type":"boolean"},"weightMultiplier":{"type":"number"}},"required":["id","districtId","courseCode","name","shortName","description","stateCourseCode","credits","gradeLevels","subjectArea","department","isHonors","isAP","isDualEnrollment","weightMultiplier"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a course","tags":["Courses"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"courseCode":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","minLength":1,"maxLength":200},"shortName":{"type":"string","maxLength":50},"description":{"type":"string","maxLength":2000},"stateCourseCode":{"type":"string","maxLength":20},"credits":{"type":"number","minimum":0,"maximum":10},"gradeLevels":{"type":"array","items":{"type":"string","maxLength":5},"default":[]},"subjectArea":{"type":"string","minLength":1,"maxLength":50},"department":{"type":"string","maxLength":100},"isHonors":{"type":"boolean","default":false},"isAP":{"type":"boolean","default":false},"isDualEnrollment":{"type":"boolean","default":false},"weightMultiplier":{"type":"number","minimum":0,"maximum":2,"default":1},"prerequisiteCourseIds":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"gradingScheme":{"type":"object","additionalProperties":{},"default":{}}},"required":["courseCode","name","subjectArea"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"courseCode":{"type":"string"},"name":{"type":"string"},"shortName":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"stateCourseCode":{"type":"string","nullable":true},"credits":{"type":"number","nullable":true},"gradeLevels":{"type":"array","items":{"type":"string"}},"subjectArea":{"type":"string"},"department":{"type":"string","nullable":true},"isHonors":{"type":"boolean"},"isAP":{"type":"boolean"},"isDualEnrollment":{"type":"boolean"},"weightMultiplier":{"type":"number"}},"required":["id","districtId","courseCode","name","shortName","description","stateCourseCode","credits","gradeLevels","subjectArea","department","isHonors","isAP","isDualEnrollment","weightMultiplier"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/courses/{id}":{"get":{"summary":"Get a course","tags":["Courses"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"courseCode":{"type":"string"},"name":{"type":"string"},"shortName":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"stateCourseCode":{"type":"string","nullable":true},"credits":{"type":"number","nullable":true},"gradeLevels":{"type":"array","items":{"type":"string"}},"subjectArea":{"type":"string"},"department":{"type":"string","nullable":true},"isHonors":{"type":"boolean"},"isAP":{"type":"boolean"},"isDualEnrollment":{"type":"boolean"},"weightMultiplier":{"type":"number"}},"required":["id","districtId","courseCode","name","shortName","description","stateCourseCode","credits","gradeLevels","subjectArea","department","isHonors","isAP","isDualEnrollment","weightMultiplier"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a course","tags":["Courses"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"courseCode":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","minLength":1,"maxLength":200},"shortName":{"type":"string","maxLength":50},"description":{"type":"string","maxLength":2000},"stateCourseCode":{"type":"string","maxLength":20},"credits":{"type":"number","minimum":0,"maximum":10},"gradeLevels":{"type":"array","items":{"type":"string","maxLength":5},"default":[]},"subjectArea":{"type":"string","minLength":1,"maxLength":50},"department":{"type":"string","maxLength":100},"isHonors":{"type":"boolean","default":false},"isAP":{"type":"boolean","default":false},"isDualEnrollment":{"type":"boolean","default":false},"weightMultiplier":{"type":"number","minimum":0,"maximum":2,"default":1},"prerequisiteCourseIds":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"gradingScheme":{"type":"object","additionalProperties":{},"default":{}}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"courseCode":{"type":"string"},"name":{"type":"string"},"shortName":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"stateCourseCode":{"type":"string","nullable":true},"credits":{"type":"number","nullable":true},"gradeLevels":{"type":"array","items":{"type":"string"}},"subjectArea":{"type":"string"},"department":{"type":"string","nullable":true},"isHonors":{"type":"boolean"},"isAP":{"type":"boolean"},"isDualEnrollment":{"type":"boolean"},"weightMultiplier":{"type":"number"}},"required":["id","districtId","courseCode","name","shortName","description","stateCourseCode","credits","gradeLevels","subjectArea","department","isHonors","isAP","isDualEnrollment","weightMultiplier"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sections":{"get":{"summary":"List sections","tags":["Sections"],"description":"Filter by term, course, organization, or teacher. Teacher filter returns sections where the person is a primary or co-teacher in an active participation.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"termId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"courseId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"organizationId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"teacherId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"courseId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"sectionCode":{"type":"string"},"name":{"type":"string"},"location":{"type":"string","nullable":true},"roomId":{"type":"string","format":"uuid","nullable":true},"periodPattern":{"type":"object","additionalProperties":{}},"capacity":{"type":"number","nullable":true},"enrollmentCount":{"type":"number"}},"required":["id","districtId","organizationId","schoolId","courseId","termId","sectionCode","name","location","roomId","periodPattern","capacity","enrollmentCount"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a section (emits SectionCreated, optionally TeacherAssignedToSection)","tags":["Sections"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"organizationId":{"type":"string","format":"uuid"},"courseId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"sectionCode":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","minLength":1,"maxLength":200},"location":{"type":"string","maxLength":100},"roomId":{"type":"string","format":"uuid"},"periodPattern":{"type":"object","additionalProperties":{},"default":{}},"capacity":{"type":"integer","exclusiveMinimum":true,"minimum":0},"teacherId":{"type":"string","format":"uuid"}},"required":["organizationId","courseId","termId","sectionCode","name"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"section":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"courseId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"sectionCode":{"type":"string"},"name":{"type":"string"},"location":{"type":"string","nullable":true},"roomId":{"type":"string","format":"uuid","nullable":true},"periodPattern":{"type":"object","additionalProperties":{}},"capacity":{"type":"number","nullable":true},"enrollmentCount":{"type":"number"}},"required":["id","districtId","organizationId","schoolId","courseId","termId","sectionCode","name","location","roomId","periodPattern","capacity","enrollmentCount"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["section","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sections/{id}":{"get":{"summary":"Get a section","tags":["Sections"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"courseId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"sectionCode":{"type":"string"},"name":{"type":"string"},"location":{"type":"string","nullable":true},"roomId":{"type":"string","format":"uuid","nullable":true},"periodPattern":{"type":"object","additionalProperties":{}},"capacity":{"type":"number","nullable":true},"enrollmentCount":{"type":"number"}},"required":["id","districtId","organizationId","schoolId","courseId","termId","sectionCode","name","location","roomId","periodPattern","capacity","enrollmentCount"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a section (emits SectionScheduleChanged if the schedule changes)","tags":["Sections"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"organizationId":{"type":"string","format":"uuid"},"courseId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"sectionCode":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","minLength":1,"maxLength":200},"location":{"type":"string","maxLength":100},"periodPattern":{"type":"object","additionalProperties":{},"default":{}},"capacity":{"type":"integer","exclusiveMinimum":true,"minimum":0},"roomId":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"courseId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"sectionCode":{"type":"string"},"name":{"type":"string"},"location":{"type":"string","nullable":true},"roomId":{"type":"string","format":"uuid","nullable":true},"periodPattern":{"type":"object","additionalProperties":{}},"capacity":{"type":"number","nullable":true},"enrollmentCount":{"type":"number"}},"required":["id","districtId","organizationId","schoolId","courseId","termId","sectionCode","name","location","roomId","periodPattern","capacity","enrollmentCount"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sections/{id}/roster":{"get":{"summary":"Get the active roster for a section","tags":["Sections"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"participationId":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["STUDENT","PRIMARY_TEACHER","CO_TEACHER","TEACHING_ASSISTANT","AIDE","OBSERVER"]},"firstName":{"type":"string"},"lastName":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true}},"required":["participationId","personId","role","firstName","lastName","startDate","endDate"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/participations":{"post":{"summary":"Add a person to a section (student, teacher, aide, observer)","tags":["Sections"],"description":"Emits StudentAddedToSection for students, TeacherAssignedToSection for PRIMARY_TEACHER/CO_TEACHER.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sectionId":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["STUDENT","PRIMARY_TEACHER","CO_TEACHER","TEACHING_ASSISTANT","AIDE","OBSERVER"]},"startDate":{"type":"string","format":"date"}},"required":["sectionId","personId","role","startDate"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"participation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"sectionId":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["STUDENT","PRIMARY_TEACHER","CO_TEACHER","TEACHING_ASSISTANT","AIDE","OBSERVER"]},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true}},"required":["id","districtId","sectionId","personId","role","startDate","endDate"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["participation","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/participations/{id}/end":{"post":{"summary":"End a participation (emits StudentRemovedFromSection for students)","tags":["Sections"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"endDate":{"type":"string","format":"date"},"reason":{"type":"string","maxLength":200}},"required":["endDate"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"participation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"sectionId":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["STUDENT","PRIMARY_TEACHER","CO_TEACHER","TEACHING_ASSISTANT","AIDE","OBSERVER"]},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true}},"required":["id","districtId","sectionId","personId","role","startDate","endDate"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["participation","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assignments":{"get":{"summary":"List assignments","tags":["Gradebook"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"sectionId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"sectionId":{"type":"string","format":"uuid"},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string","nullable":true},"pointsPossible":{"type":"number"},"weight":{"type":"number"},"assignedAt":{"type":"string","format":"date-time"},"dueAt":{"type":"string","format":"date-time","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"isExtraCredit":{"type":"boolean"},"allowLate":{"type":"boolean"}},"required":["id","districtId","sectionId","name","category","description","pointsPossible","weight","assignedAt","dueAt","publishedAt","isExtraCredit","allowLate"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create an assignment (emits AssignmentCreated)","tags":["Gradebook"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sectionId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"category":{"type":"string","minLength":1,"maxLength":50},"description":{"type":"string","maxLength":2000},"pointsPossible":{"type":"number","minimum":0,"maximum":10000},"weight":{"type":"number","minimum":0,"maximum":10,"default":1},"assignedAt":{"type":"string","format":"date-time"},"dueAt":{"type":"string","format":"date-time"},"isExtraCredit":{"type":"boolean","default":false},"allowLate":{"type":"boolean","default":true}},"required":["sectionId","name","category","pointsPossible"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"sectionId":{"type":"string","format":"uuid"},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string","nullable":true},"pointsPossible":{"type":"number"},"weight":{"type":"number"},"assignedAt":{"type":"string","format":"date-time"},"dueAt":{"type":"string","format":"date-time","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"isExtraCredit":{"type":"boolean"},"allowLate":{"type":"boolean"}},"required":["id","districtId","sectionId","name","category","description","pointsPossible","weight","assignedAt","dueAt","publishedAt","isExtraCredit","allowLate"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["assignment","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assignments/{id}":{"get":{"summary":"Get an assignment","tags":["Gradebook"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"sectionId":{"type":"string","format":"uuid"},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string","nullable":true},"pointsPossible":{"type":"number"},"weight":{"type":"number"},"assignedAt":{"type":"string","format":"date-time"},"dueAt":{"type":"string","format":"date-time","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"isExtraCredit":{"type":"boolean"},"allowLate":{"type":"boolean"}},"required":["id","districtId","sectionId","name","category","description","pointsPossible","weight","assignedAt","dueAt","publishedAt","isExtraCredit","allowLate"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update an assignment","tags":["Gradebook"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"category":{"type":"string","minLength":1,"maxLength":50},"description":{"type":"string","maxLength":2000},"pointsPossible":{"type":"number","minimum":0,"maximum":10000},"weight":{"type":"number","minimum":0,"maximum":10,"default":1},"assignedAt":{"type":"string","format":"date-time"},"dueAt":{"type":"string","format":"date-time"},"isExtraCredit":{"type":"boolean","default":false},"allowLate":{"type":"boolean","default":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"sectionId":{"type":"string","format":"uuid"},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string","nullable":true},"pointsPossible":{"type":"number"},"weight":{"type":"number"},"assignedAt":{"type":"string","format":"date-time"},"dueAt":{"type":"string","format":"date-time","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"isExtraCredit":{"type":"boolean"},"allowLate":{"type":"boolean"}},"required":["id","districtId","sectionId","name","category","description","pointsPossible","weight","assignedAt","dueAt","publishedAt","isExtraCredit","allowLate"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assignments/{id}/scores":{"get":{"summary":"List scores for an assignment","tags":["Gradebook"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"points":{"type":"number","nullable":true},"percent":{"type":"number","nullable":true},"submittedAt":{"type":"string","format":"date-time","nullable":true},"gradedAt":{"type":"string","format":"date-time","nullable":true},"comment":{"type":"string","nullable":true},"isMissing":{"type":"boolean"},"isExempt":{"type":"boolean"},"isLate":{"type":"boolean"}},"required":["id","studentPersonId","points","percent","submittedAt","gradedAt","comment","isMissing","isExempt","isLate"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Bulk enter scores (emits AssignmentScored per student)","tags":["Gradebook"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scores":{"type":"array","items":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"points":{"type":"number","nullable":true},"percent":{"type":"number","nullable":true},"comment":{"type":"string","maxLength":1000},"isMissing":{"type":"boolean"},"isExempt":{"type":"boolean"},"isLate":{"type":"boolean"}},"required":["studentId"],"additionalProperties":false},"minItems":1,"maxItems":200}},"required":["scores"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"accepted":{"type":"integer"},"eventIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["accepted","eventIds"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/grades/current":{"get":{"summary":"Query the section-grade projection","tags":["Gradebook"],"description":"Reads from projection_section_grades. Eventually consistent — freshly entered scores may take a few seconds to reflect.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"sectionId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"termId","required":false},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sectionId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"percentGrade":{"type":"number","nullable":true},"letterGrade":{"type":"string","nullable":true},"gpaValue":{"type":"number","nullable":true},"missingAssignments":{"type":"number"},"lastEventId":{"type":"string"}},"required":["sectionId","studentPersonId","termId","percentGrade","letterGrade","gpaValue","missingAssignments","lastEventId"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sections/{id}/gradebook":{"get":{"summary":"Complete gradebook view for a section","tags":["Gradebook"],"description":"Returns the section, its active student roster, all assignments, and every score. Suitable for the teacher portal gradebook page.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"section":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sectionCode":{"type":"string"},"name":{"type":"string"},"termId":{"type":"string","format":"uuid"}},"required":["id","sectionCode","name","termId"],"additionalProperties":false},"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"category":{"type":"string"},"pointsPossible":{"type":"number"},"dueAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","name","category","pointsPossible","dueAt"],"additionalProperties":false}},"students":{"type":"array","items":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"}},"required":["personId","firstName","lastName"],"additionalProperties":false}},"scores":{"type":"array","items":{"type":"object","properties":{"assignmentId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"points":{"type":"number","nullable":true},"percent":{"type":"number","nullable":true}},"required":["assignmentId","studentPersonId","points","percent"],"additionalProperties":false}}},"required":["section","assignments","students","scores"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sections/{id}/actions/publish-grades":{"post":{"summary":"Publish final grades for the term (emits SectionGradePosted per student)","tags":["Gradebook"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"termId":{"type":"string","format":"uuid"},"grades":{"type":"array","items":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"letterGrade":{"type":"string","maxLength":5},"percent":{"type":"number","minimum":0,"maximum":200}},"required":["studentId"],"additionalProperties":false},"minItems":1,"maxItems":500}},"required":["termId","grades"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"published":{"type":"integer"},"eventIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["published","eventIds"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/notification-preferences":{"get":{"summary":"Get notification preferences for the signed-in guardian","tags":["Parent Portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"attendance":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"grades":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"announcements":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"fees":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"iep504":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"health":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"emergency":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false}},"required":["attendance","grades","announcements","fees","iep504","health","emergency"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update notification preferences for the signed-in guardian","tags":["Parent Portal"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"attendance":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"grades":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"announcements":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"fees":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"iep504":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"health":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"emergency":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false}},"required":["attendance","grades","announcements","fees","iep504","health","emergency"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"attendance":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"grades":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"announcements":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"fees":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"iep504":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"health":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false},"emergency":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","sms","push"],"additionalProperties":false}},"required":["attendance","grades","announcements","fees","iep504","health","emergency"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/students":{"get":{"summary":"List students linked to the signed-in guardian","tags":["Parent Portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"attendanceRate":{"type":"number","nullable":true},"currentGpa":{"type":"number","nullable":true},"missingAssignments":{"type":"number"}},"required":["studentId","firstName","lastName","gradeLevel","attendanceRate","currentGpa","missingAssignments"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/students/{id}/attendance":{"get":{"summary":"Attendance days for one of the guardian's students","tags":["Parent Portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"status":{"type":"string"},"code":{"type":"string"}},"required":["date","status","code"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/students/{id}/grades":{"get":{"summary":"Current grades for one of the guardian's students","tags":["Parent Portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sectionId":{"type":"string","format":"uuid"},"sectionName":{"type":"string"},"courseCode":{"type":"string"},"percentGrade":{"type":"number","nullable":true},"letterGrade":{"type":"string","nullable":true},"missingAssignments":{"type":"number"}},"required":["sectionId","sectionName","courseCode","percentGrade","letterGrade","missingAssignments"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/students/{id}/assignments":{"get":{"summary":"Upcoming + recent assignments for one of the guardian's students","tags":["Parent Portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sectionId":{"type":"string","format":"uuid"},"sectionName":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"pointsPossible":{"type":"number"},"dueAt":{"type":"string","format":"date-time","nullable":true},"points":{"type":"number","nullable":true},"percent":{"type":"number","nullable":true}},"required":["id","sectionId","sectionName","name","category","pointsPossible","dueAt","points","percent"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/students/{id}":{"get":{"summary":"Student summary card (attendance rate + GPA + current sections)","tags":["Parent Portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel"],"additionalProperties":false},"metrics":{"type":"object","properties":{"attendanceRate":{"type":"number","nullable":true},"tardyCount":{"type":"number"},"disciplineIncidents":{"type":"number"}},"required":["attendanceRate","tardyCount","disciplineIncidents"],"additionalProperties":false},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"sectionCode":{"type":"string"}},"required":["id","name","sectionCode"],"additionalProperties":false}}},"required":["student","metrics","sections"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/students/{id}/schedule":{"get":{"summary":"Current schedule for one of the guardian's students","tags":["Parent Portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sectionId":{"type":"string","format":"uuid"},"sectionName":{"type":"string"},"sectionCode":{"type":"string"},"courseCode":{"type":"string"},"courseName":{"type":"string"},"teacherName":{"type":"string","nullable":true},"roomNumber":{"type":"string","nullable":true},"periodPattern":{"type":"object","additionalProperties":{}}},"required":["sectionId","sectionName","sectionCode","courseCode","courseName","teacherName","roomNumber","periodPattern"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/inbox":{"get":{"summary":"Messages addressed to the signed-in guardian","tags":["Parent Portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"channel":{"type":"string"},"sentAt":{"type":"string","format":"date-time","nullable":true},"senderName":{"type":"string","nullable":true},"isRead":{"type":"boolean"}},"required":["id","subject","body","channel","sentAt","senderName","isRead"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/student/me":{"get":{"summary":"Signed-in student profile","tags":["Student Portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"schoolName":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","schoolName"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/student/me/schedule":{"get":{"summary":"Signed-in student's current schedule","tags":["Student Portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sectionId":{"type":"string","format":"uuid"},"sectionName":{"type":"string"},"sectionCode":{"type":"string"},"courseCode":{"type":"string"},"courseName":{"type":"string"},"teacherName":{"type":"string","nullable":true},"roomNumber":{"type":"string","nullable":true},"periodPattern":{"type":"object","additionalProperties":{}}},"required":["sectionId","sectionName","sectionCode","courseCode","courseName","teacherName","roomNumber","periodPattern"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/student/me/attendance":{"get":{"summary":"Signed-in student's attendance history","tags":["Student Portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"status":{"type":"string"},"code":{"type":"string"}},"required":["date","status","code"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/student/me/grades":{"get":{"summary":"Signed-in student's current grades","tags":["Student Portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sectionId":{"type":"string","format":"uuid"},"sectionName":{"type":"string"},"courseCode":{"type":"string"},"percentGrade":{"type":"number","nullable":true},"letterGrade":{"type":"string","nullable":true},"missingAssignments":{"type":"number"}},"required":["sectionId","sectionName","courseCode","percentGrade","letterGrade","missingAssignments"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/student/me/assignments":{"get":{"summary":"Signed-in student's upcoming + recent assignments","tags":["Student Portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sectionName":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"pointsPossible":{"type":"number"},"dueAt":{"type":"string","format":"date-time","nullable":true},"points":{"type":"number","nullable":true},"percent":{"type":"number","nullable":true}},"required":["id","sectionName","name","category","pointsPossible","dueAt","points","percent"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/course-requests":{"get":{"summary":"List course requests","tags":["Scheduling"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"termId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"string","enum":["pending","scheduled","unscheduled","waived"]},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"courseId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"priority":{"type":"integer"},"status":{"type":"string"},"assignedSectionId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","districtId","studentPersonId","courseId","termId","priority","status","assignedSectionId","notes"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a course request","tags":["Scheduling"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"courseId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"priority":{"type":"integer","minimum":1,"maximum":100,"default":1},"notes":{"type":"string","maxLength":500}},"required":["studentId","courseId","termId"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"courseId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"priority":{"type":"integer"},"status":{"type":"string"},"assignedSectionId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","districtId","studentPersonId","courseId","termId","priority","status","assignedSectionId","notes"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/course-requests/{id}":{"get":{"summary":"Get a course request","tags":["Scheduling"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"courseId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"priority":{"type":"integer"},"status":{"type":"string"},"assignedSectionId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","districtId","studentPersonId","courseId","termId","priority","status","assignedSectionId","notes"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a course request","tags":["Scheduling"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"priority":{"type":"integer","minimum":1,"maximum":100},"status":{"type":"string","enum":["pending","scheduled","unscheduled","waived"]},"notes":{"type":"string","maxLength":500}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"courseId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"priority":{"type":"integer"},"status":{"type":"string"},"assignedSectionId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","districtId","studentPersonId","courseId","termId","priority","status","assignedSectionId","notes"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a course request","tags":["Scheduling"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/scheduling/master-schedule":{"get":{"summary":"Master schedule for a term (sections + live conflicts)","tags":["Scheduling"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"termId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sectionCode":{"type":"string"},"name":{"type":"string"},"courseCode":{"type":"string"},"courseName":{"type":"string"},"teacherPersonId":{"type":"string","format":"uuid","nullable":true},"teacherParticipationId":{"type":"string","format":"uuid","nullable":true},"teacherName":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"capacity":{"type":"integer","nullable":true},"enrollmentCount":{"type":"integer"},"periodPattern":{"type":"object","additionalProperties":{}}},"required":["id","sectionCode","name","courseCode","courseName","teacherPersonId","teacherParticipationId","teacherName","location","capacity","enrollmentCount","periodPattern"],"additionalProperties":false}},"conflicts":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"message":{"type":"string"},"slot":{"type":"object","properties":{"day":{"type":"string"},"period":{"type":"string"}},"required":["day","period"],"additionalProperties":false}},"required":["kind","sectionIds","message"],"additionalProperties":false}}},"required":["sections","conflicts"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/scheduling/conflicts":{"get":{"summary":"Detect master-schedule conflicts for a term","tags":["Scheduling"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"termId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"message":{"type":"string"},"slot":{"type":"object","properties":{"day":{"type":"string"},"period":{"type":"string"}},"required":["day","period"],"additionalProperties":false}},"required":["kind","sectionIds","message"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/scheduling/propose":{"post":{"summary":"Run the CSP solver and return a proposed assignment (no writes)","tags":["Scheduling"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"termId":{"type":"string","format":"uuid"},"timeBudgetMs":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":30000,"default":5000},"studentIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["termId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"assignments":{"type":"array","items":{"type":"object","properties":{"courseRequestId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"sectionId":{"type":"string","format":"uuid"}},"required":["courseRequestId","studentPersonId","sectionId"],"additionalProperties":false}},"unscheduled":{"type":"array","items":{"type":"object","properties":{"courseRequestId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"courseId":{"type":"string","format":"uuid"},"reason":{"type":"string"}},"required":["courseRequestId","studentPersonId","courseId","reason"],"additionalProperties":false}},"hitTimeLimit":{"type":"boolean"},"sectionLoad":{"type":"object","additionalProperties":{"type":"integer"}}},"required":["assignments","unscheduled","hitTimeLimit","sectionLoad"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/scheduling/publish":{"post":{"summary":"Apply a proposal: create participations + mark course requests scheduled + emit StudentScheduled events","tags":["Scheduling"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"termId":{"type":"string","format":"uuid"},"assignments":{"type":"array","items":{"type":"object","properties":{"courseRequestId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"sectionId":{"type":"string","format":"uuid"}},"required":["courseRequestId","studentPersonId","sectionId"],"additionalProperties":false},"minItems":1,"maxItems":2000},"effectiveDate":{"type":"string","format":"date"}},"required":["termId","assignments","effectiveDate"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"createdParticipations":{"type":"integer"},"eventIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["createdParticipations","eventIds"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/health/visits":{"get":{"summary":"List nurse visits","tags":["Health"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"to","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"visitAt":{"type":"string","format":"date-time"},"chiefComplaint":{"type":"string"},"disposition":{"type":"string"},"notes":{"type":"string","nullable":true},"durationMinutes":{"type":"integer","nullable":true}},"required":["id","studentPersonId","visitAt","chiefComplaint","disposition","notes","durationMinutes"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Record a nurse visit (emits HealthEncounter)","tags":["Health"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"visitAt":{"type":"string","format":"date-time"},"chiefComplaint":{"type":"string","minLength":1,"maxLength":200},"disposition":{"type":"string","minLength":1,"maxLength":60},"notes":{"type":"string","maxLength":2000},"durationMinutes":{"type":"integer","minimum":0,"maximum":480},"bodyLocation":{"type":"string","maxLength":200},"painScale":{"type":"integer","minimum":0,"maximum":10},"temperatureF":{"type":"number","minimum":70,"maximum":115},"pulse":{"type":"integer","minimum":20,"maximum":250},"respirations":{"type":"integer","minimum":4,"maximum":80},"bloodPressure":{"type":"string","maxLength":20},"oxygenSaturation":{"type":"integer","minimum":50,"maximum":100},"medicationGiven":{"type":"string","maxLength":200},"medicationDose":{"type":"string","maxLength":100},"followUpPlan":{"type":"string","enum":["none","monitor","recheck","physician"]},"parentContacted":{"type":"boolean"}},"required":["studentId","chiefComplaint","disposition"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"visit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"visitAt":{"type":"string","format":"date-time"},"chiefComplaint":{"type":"string"},"disposition":{"type":"string"},"notes":{"type":"string","nullable":true},"durationMinutes":{"type":"integer","nullable":true}},"required":["id","studentPersonId","visitAt","chiefComplaint","disposition","notes","durationMinutes"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["visit","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/health/visits/{id}":{"get":{"summary":"Get a nurse visit","tags":["Health"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"visitAt":{"type":"string","format":"date-time"},"chiefComplaint":{"type":"string"},"disposition":{"type":"string"},"notes":{"type":"string","nullable":true},"durationMinutes":{"type":"integer","nullable":true}},"required":["id","studentPersonId","visitAt","chiefComplaint","disposition","notes","durationMinutes"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/health/medications":{"get":{"summary":"List medication prescriptions","tags":["Health"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"boolean","default":true},"in":"query","name":"activeOnly","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"name":{"type":"string"},"dose":{"type":"string"},"route":{"type":"string"},"scheduleJson":{"type":"object","additionalProperties":{}},"prescriberName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"isActive":{"type":"boolean"},"controlledSubstance":{"type":"string","enum":["none","schedule_ii","schedule_iii_v"]},"frequency":{"type":"string","enum":["scheduled","prn"]},"parentConsentOn":{"type":"string","format":"date-time","nullable":true},"prescriptionOnFile":{"type":"boolean"},"discontinuedOn":{"type":"string","format":"date-time","nullable":true},"discontinueReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","studentPersonId","name","dose","route","scheduleJson","prescriberName","startDate","endDate","isActive","controlledSubstance","frequency","parentConsentOn","prescriptionOnFile","discontinuedOn","discontinueReason","notes"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Record a medication prescription","tags":["Health"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"dose":{"type":"string","minLength":1,"maxLength":100},"route":{"type":"string","enum":["oral","topical","injection","inhalation","other"]},"scheduleJson":{"type":"object","properties":{"times":{"type":"array","items":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"default":[]},"daysOfWeek":{"type":"array","items":{"type":"integer","minimum":1,"maximum":7}},"prnReason":{"type":"string","maxLength":300}},"additionalProperties":false,"default":{"times":[]}},"prescriberName":{"type":"string","maxLength":200},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"controlledSubstance":{"type":"string","enum":["none","schedule_ii","schedule_iii_v"],"default":"none"},"frequency":{"type":"string","enum":["scheduled","prn"],"default":"scheduled"},"parentConsentOn":{"type":"string","format":"date-time"},"prescriptionOnFile":{"type":"boolean","default":false},"notes":{"type":"string","maxLength":2000}},"required":["studentId","name","dose","route","startDate"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"name":{"type":"string"},"dose":{"type":"string"},"route":{"type":"string"},"scheduleJson":{"type":"object","additionalProperties":{}},"prescriberName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"isActive":{"type":"boolean"},"controlledSubstance":{"type":"string","enum":["none","schedule_ii","schedule_iii_v"]},"frequency":{"type":"string","enum":["scheduled","prn"]},"parentConsentOn":{"type":"string","format":"date-time","nullable":true},"prescriptionOnFile":{"type":"boolean"},"discontinuedOn":{"type":"string","format":"date-time","nullable":true},"discontinueReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","studentPersonId","name","dose","route","scheduleJson","prescriberName","startDate","endDate","isActive","controlledSubstance","frequency","parentConsentOn","prescriptionOnFile","discontinuedOn","discontinueReason","notes"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/health/medications/due":{"get":{"summary":"Scheduled doses due today","tags":["Health"],"description":"Returns one row per (med × scheduled time) for active scheduled orders today. PRN orders are not included.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"medicationId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"medicationName":{"type":"string"},"dose":{"type":"string"},"route":{"type":"string"},"scheduledFor":{"type":"string","format":"date-time"},"controlledSubstance":{"type":"string"},"lastDoseAt":{"type":"string","format":"date-time","nullable":true},"alreadyGivenToday":{"type":"boolean"}},"required":["medicationId","studentPersonId","studentName","medicationName","dose","route","scheduledFor","controlledSubstance","lastDoseAt","alreadyGivenToday"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/health/medications/{id}":{"get":{"summary":"Get a medication","tags":["Health"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"name":{"type":"string"},"dose":{"type":"string"},"route":{"type":"string"},"scheduleJson":{"type":"object","additionalProperties":{}},"prescriberName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"isActive":{"type":"boolean"},"controlledSubstance":{"type":"string","enum":["none","schedule_ii","schedule_iii_v"]},"frequency":{"type":"string","enum":["scheduled","prn"]},"parentConsentOn":{"type":"string","format":"date-time","nullable":true},"prescriptionOnFile":{"type":"boolean"},"discontinuedOn":{"type":"string","format":"date-time","nullable":true},"discontinueReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","studentPersonId","name","dose","route","scheduleJson","prescriberName","startDate","endDate","isActive","controlledSubstance","frequency","parentConsentOn","prescriptionOnFile","discontinuedOn","discontinueReason","notes"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a medication order (cannot change controlled-substance class)","tags":["Health"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"endDate":{"type":"string","format":"date","nullable":true},"scheduleJson":{"type":"object","properties":{"times":{"type":"array","items":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"default":[]},"daysOfWeek":{"type":"array","items":{"type":"integer","minimum":1,"maximum":7}},"prnReason":{"type":"string","maxLength":300}},"additionalProperties":false},"prescriberName":{"type":"string","maxLength":200,"nullable":true},"parentConsentOn":{"type":"string","format":"date-time","nullable":true},"prescriptionOnFile":{"type":"boolean"},"notes":{"type":"string","maxLength":2000,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"name":{"type":"string"},"dose":{"type":"string"},"route":{"type":"string"},"scheduleJson":{"type":"object","additionalProperties":{}},"prescriberName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"isActive":{"type":"boolean"},"controlledSubstance":{"type":"string","enum":["none","schedule_ii","schedule_iii_v"]},"frequency":{"type":"string","enum":["scheduled","prn"]},"parentConsentOn":{"type":"string","format":"date-time","nullable":true},"prescriptionOnFile":{"type":"boolean"},"discontinuedOn":{"type":"string","format":"date-time","nullable":true},"discontinueReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","studentPersonId","name","dose","route","scheduleJson","prescriberName","startDate","endDate","isActive","controlledSubstance","frequency","parentConsentOn","prescriptionOnFile","discontinuedOn","discontinueReason","notes"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/health/medications/{id}/administrations":{"get":{"summary":"Administration history for a medication","tags":["Health"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"medicationId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"administeredAt":{"type":"string","format":"date-time"},"doseGivenText":{"type":"string"},"administeredByUserId":{"type":"string"},"witnessUserId":{"type":"string","nullable":true},"status":{"type":"string","enum":["given","refused","missed","held"]},"route":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","medicationId","studentPersonId","administeredAt","doseGivenText","administeredByUserId","witnessUserId","status","route","notes","createdAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/health/medications/{id}/discontinue":{"post":{"summary":"Discontinue a medication order","tags":["Health"],"description":"Flags the order inactive with a reason; further \"due\" rows and new doses are blocked. History remains.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"name":{"type":"string"},"dose":{"type":"string"},"route":{"type":"string"},"scheduleJson":{"type":"object","additionalProperties":{}},"prescriberName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"isActive":{"type":"boolean"},"controlledSubstance":{"type":"string","enum":["none","schedule_ii","schedule_iii_v"]},"frequency":{"type":"string","enum":["scheduled","prn"]},"parentConsentOn":{"type":"string","format":"date-time","nullable":true},"prescriptionOnFile":{"type":"boolean"},"discontinuedOn":{"type":"string","format":"date-time","nullable":true},"discontinueReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","studentPersonId","name","dose","route","scheduleJson","prescriberName","startDate","endDate","isActive","controlledSubstance","frequency","parentConsentOn","prescriptionOnFile","discontinuedOn","discontinueReason","notes"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/health/medications/administrations":{"post":{"summary":"Log a medication administration (emits MedicationAdministered)","tags":["Health"],"description":"Supports status = given | refused | missed | held. Schedule-II controlled meds require a second-nurse `witnessUserId` on any dose with status=given.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"medicationId":{"type":"string","format":"uuid"},"studentId":{"type":"string","format":"uuid"},"administeredAt":{"type":"string","format":"date-time"},"doseGivenText":{"type":"string","minLength":1,"maxLength":100},"witnessUserId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["given","refused","missed","held"],"default":"given"},"route":{"type":"string","enum":["oral","topical","injection","inhalation","other"]},"notes":{"type":"string","maxLength":2000}},"required":["medicationId","studentId","doseGivenText"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"administrationId":{"type":"string","format":"uuid"},"eventId":{"type":"string","format":"uuid"}},"required":["administrationId","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/students/{id}/medications":{"get":{"summary":"Active medications + recent doses for a guardian's student","tags":["Parent Portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"medications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"name":{"type":"string"},"dose":{"type":"string"},"route":{"type":"string"},"scheduleJson":{"type":"object","additionalProperties":{}},"prescriberName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"isActive":{"type":"boolean"},"controlledSubstance":{"type":"string","enum":["none","schedule_ii","schedule_iii_v"]},"frequency":{"type":"string","enum":["scheduled","prn"]},"parentConsentOn":{"type":"string","format":"date-time","nullable":true},"prescriptionOnFile":{"type":"boolean"},"discontinuedOn":{"type":"string","format":"date-time","nullable":true},"discontinueReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","studentPersonId","name","dose","route","scheduleJson","prescriberName","startDate","endDate","isActive","controlledSubstance","frequency","parentConsentOn","prescriptionOnFile","discontinuedOn","discontinueReason","notes"],"additionalProperties":false}},"recentAdministrations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"medicationId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"administeredAt":{"type":"string","format":"date-time"},"doseGivenText":{"type":"string"},"administeredByUserId":{"type":"string"},"witnessUserId":{"type":"string","nullable":true},"status":{"type":"string","enum":["given","refused","missed","held"]},"route":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","medicationId","studentPersonId","administeredAt","doseGivenText","administeredByUserId","witnessUserId","status","route","notes","createdAt"],"additionalProperties":false}}},"required":["medications","recentAdministrations"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/student/me/medications":{"get":{"summary":"The signed-in student's active medications + recent doses","tags":["Student Portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"medications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"name":{"type":"string"},"dose":{"type":"string"},"route":{"type":"string"},"scheduleJson":{"type":"object","additionalProperties":{}},"prescriberName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"isActive":{"type":"boolean"},"controlledSubstance":{"type":"string","enum":["none","schedule_ii","schedule_iii_v"]},"frequency":{"type":"string","enum":["scheduled","prn"]},"parentConsentOn":{"type":"string","format":"date-time","nullable":true},"prescriptionOnFile":{"type":"boolean"},"discontinuedOn":{"type":"string","format":"date-time","nullable":true},"discontinueReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","studentPersonId","name","dose","route","scheduleJson","prescriberName","startDate","endDate","isActive","controlledSubstance","frequency","parentConsentOn","prescriptionOnFile","discontinuedOn","discontinueReason","notes"],"additionalProperties":false}},"recentAdministrations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"medicationId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"administeredAt":{"type":"string","format":"date-time"},"doseGivenText":{"type":"string"},"administeredByUserId":{"type":"string"},"witnessUserId":{"type":"string","nullable":true},"status":{"type":"string","enum":["given","refused","missed","held"]},"route":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","medicationId","studentPersonId","administeredAt","doseGivenText","administeredByUserId","witnessUserId","status","route","notes","createdAt"],"additionalProperties":false}}},"required":["medications","recentAdministrations"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/students/{id}/screenings":{"get":{"summary":"Recent health screenings for a guardianed student","tags":["Parent Portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"screenings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"screeningType":{"type":"string","enum":["vision","hearing","scoliosis","bmi","blood_pressure"]},"performedOn":{"type":"string","format":"date"},"result":{"type":"object","additionalProperties":{}},"status":{"type":"string","enum":["normal","abnormal","inconclusive"]},"followupNeeded":{"type":"boolean"},"schoolId":{"type":"string","format":"uuid","nullable":true},"performedByUserId":{"type":"string","nullable":true},"gradeAtScreening":{"type":"string","nullable":true},"referralSentOn":{"type":"string","format":"date-time","nullable":true},"referralNotes":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","screeningType","performedOn","result","status","followupNeeded","schoolId","performedByUserId","gradeAtScreening","referralSentOn","referralNotes","notes","createdAt"],"additionalProperties":false}}},"required":["screenings"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/student/me/screenings":{"get":{"summary":"The signed-in student's recent health screenings","tags":["Student Portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"screenings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"screeningType":{"type":"string","enum":["vision","hearing","scoliosis","bmi","blood_pressure"]},"performedOn":{"type":"string","format":"date"},"result":{"type":"object","additionalProperties":{}},"status":{"type":"string","enum":["normal","abnormal","inconclusive"]},"followupNeeded":{"type":"boolean"},"schoolId":{"type":"string","format":"uuid","nullable":true},"performedByUserId":{"type":"string","nullable":true},"gradeAtScreening":{"type":"string","nullable":true},"referralSentOn":{"type":"string","format":"date-time","nullable":true},"referralNotes":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","screeningType","performedOn","result","status","followupNeeded","schoolId","performedByUserId","gradeAtScreening","referralSentOn","referralNotes","notes","createdAt"],"additionalProperties":false}}},"required":["screenings"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/health/immunizations":{"get":{"summary":"List immunization records","tags":["Health"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"vaccineCode":{"type":"string"},"vaccineName":{"type":"string"},"administeredOn":{"type":"string","format":"date"},"provider":{"type":"string","nullable":true},"lotNumber":{"type":"string","nullable":true},"source":{"type":"string"}},"required":["id","studentPersonId","vaccineCode","vaccineName","administeredOn","provider","lotNumber","source"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Record an immunization (emits ImmunizationRecorded)","tags":["Health"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"vaccineCode":{"type":"string","minLength":1,"maxLength":30},"vaccineName":{"type":"string","minLength":1,"maxLength":200},"administeredOn":{"type":"string","format":"date"},"provider":{"type":"string","maxLength":200},"lotNumber":{"type":"string","maxLength":50},"source":{"type":"string","enum":["manual","njiis","import"],"default":"manual"}},"required":["studentId","vaccineCode","vaccineName","administeredOn"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"immunization":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"vaccineCode":{"type":"string"},"vaccineName":{"type":"string"},"administeredOn":{"type":"string","format":"date"},"provider":{"type":"string","nullable":true},"lotNumber":{"type":"string","nullable":true},"source":{"type":"string"}},"required":["id","studentPersonId","vaccineCode","vaccineName","administeredOn","provider","lotNumber","source"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["immunization","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/health/immunizations/njiis-sync":{"post":{"summary":"Trigger NJIIS immunization sync for this district","tags":["Health"],"description":"Queries NJIIS for all active students, upserts matched vaccination records, detects conflicts with manually-entered data. Credentials must be configured via NJIIS_USERNAME / NJIIS_PASSWORD / NJIIS_FACILITY env vars (or district-scoped equivalents).","responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"syncId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued"]},"message":{"type":"string"}},"required":["syncId","status","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/health/immunizations/njiis-status":{"get":{"summary":"NJIIS sync status and history for this district","tags":["Health"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"lastSyncAt":{"type":"string","format":"date-time","nullable":true},"lastSyncStatus":{"type":"string","nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"startedAt":{"type":"string"},"completedAt":{"type":"string"},"studentsQueried":{"type":"integer"},"studentsMatched":{"type":"integer"},"recordsPulled":{"type":"integer"},"recordsUpserted":{"type":"integer"},"conflictsFound":{"type":"integer"},"failures":{"type":"integer"},"status":{"type":"string"},"error":{"type":"string","nullable":true}},"required":["startedAt","completedAt","studentsQueried","studentsMatched","recordsPulled","recordsUpserted","conflictsFound","failures","status","error"],"additionalProperties":false}}},"required":["lastSyncAt","lastSyncStatus","history"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/health/screenings":{"get":{"summary":"List health screenings","tags":["Health"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"string","enum":["vision","hearing","scoliosis","bmi","blood_pressure"]},"in":"query","name":"type","required":false},{"schema":{"type":"string","enum":["normal","abnormal","inconclusive"]},"in":"query","name":"status","required":false},{"schema":{"type":"boolean","default":false},"in":"query","name":"followupOnly","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"screeningType":{"type":"string","enum":["vision","hearing","scoliosis","bmi","blood_pressure"]},"performedOn":{"type":"string","format":"date"},"result":{"type":"object","additionalProperties":{}},"status":{"type":"string","enum":["normal","abnormal","inconclusive"]},"followupNeeded":{"type":"boolean"},"schoolId":{"type":"string","format":"uuid","nullable":true},"performedByUserId":{"type":"string","nullable":true},"gradeAtScreening":{"type":"string","nullable":true},"referralSentOn":{"type":"string","format":"date-time","nullable":true},"referralNotes":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","screeningType","performedOn","result","status","followupNeeded","schoolId","performedByUserId","gradeAtScreening","referralSentOn","referralNotes","notes","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Record a health screening (emits HealthScreeningCompleted)","tags":["Health"],"description":"Status is derived from the result unless explicitly overridden. Abnormal results automatically set followupNeeded=true so the referral queue picks them up.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"screeningType":{"type":"string","enum":["vision","hearing","scoliosis","bmi","blood_pressure"]},"performedOn":{"type":"string","format":"date"},"result":{"type":"object","additionalProperties":{}},"notes":{"type":"string","maxLength":2000},"schoolId":{"type":"string","format":"uuid"},"gradeAtScreening":{"type":"string","maxLength":20},"status":{"type":"string","enum":["normal","abnormal","inconclusive"]}},"required":["studentId","screeningType","performedOn","result"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"screeningType":{"type":"string","enum":["vision","hearing","scoliosis","bmi","blood_pressure"]},"performedOn":{"type":"string","format":"date"},"result":{"type":"object","additionalProperties":{}},"status":{"type":"string","enum":["normal","abnormal","inconclusive"]},"followupNeeded":{"type":"boolean"},"schoolId":{"type":"string","format":"uuid","nullable":true},"performedByUserId":{"type":"string","nullable":true},"gradeAtScreening":{"type":"string","nullable":true},"referralSentOn":{"type":"string","format":"date-time","nullable":true},"referralNotes":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","screeningType","performedOn","result","status","followupNeeded","schoolId","performedByUserId","gradeAtScreening","referralSentOn","referralNotes","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/health/screenings/compliance":{"get":{"summary":"Screening compliance matrix (who still owes what this year)","tags":["Health"],"description":"Returns one row per (student × required screening) for the current school year. `satisfied` means there is a screening of that type on file since Aug 1. Use to surface a nurse-side \"still to do\" list.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"organizationId","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"asOf","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string"},"screeningType":{"type":"string","enum":["vision","hearing","scoliosis","bmi","blood_pressure"]},"satisfied":{"type":"boolean"},"mostRecentOn":{"type":"string","format":"date","nullable":true},"mostRecentStatus":{"type":"string","enum":["normal","abnormal","inconclusive"],"nullable":true}},"required":["studentPersonId","studentName","gradeLevel","screeningType","satisfied","mostRecentOn","mostRecentStatus"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/health/screenings/{id}":{"get":{"summary":"Get a screening","tags":["Health"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"screeningType":{"type":"string","enum":["vision","hearing","scoliosis","bmi","blood_pressure"]},"performedOn":{"type":"string","format":"date"},"result":{"type":"object","additionalProperties":{}},"status":{"type":"string","enum":["normal","abnormal","inconclusive"]},"followupNeeded":{"type":"boolean"},"schoolId":{"type":"string","format":"uuid","nullable":true},"performedByUserId":{"type":"string","nullable":true},"gradeAtScreening":{"type":"string","nullable":true},"referralSentOn":{"type":"string","format":"date-time","nullable":true},"referralNotes":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","screeningType","performedOn","result","status","followupNeeded","schoolId","performedByUserId","gradeAtScreening","referralSentOn","referralNotes","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Edit a screening (correct a typo, update notes, override status)","tags":["Health"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object","additionalProperties":{}},"notes":{"type":"string","maxLength":2000,"nullable":true},"status":{"type":"string","enum":["normal","abnormal","inconclusive"]},"followupNeeded":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"screeningType":{"type":"string","enum":["vision","hearing","scoliosis","bmi","blood_pressure"]},"performedOn":{"type":"string","format":"date"},"result":{"type":"object","additionalProperties":{}},"status":{"type":"string","enum":["normal","abnormal","inconclusive"]},"followupNeeded":{"type":"boolean"},"schoolId":{"type":"string","format":"uuid","nullable":true},"performedByUserId":{"type":"string","nullable":true},"gradeAtScreening":{"type":"string","nullable":true},"referralSentOn":{"type":"string","format":"date-time","nullable":true},"referralNotes":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","screeningType","performedOn","result","status","followupNeeded","schoolId","performedByUserId","gradeAtScreening","referralSentOn","referralNotes","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/health/screenings/{id}/referral":{"post":{"summary":"Record that a family referral was sent for an abnormal screening","tags":["Health"],"description":"Stamps `referralSentOn` and appends a note. Emits ScreeningReferralSent. Only valid on screenings where followupNeeded=true.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","minLength":3,"maxLength":2000},"sentOn":{"type":"string","format":"date"}},"required":["notes"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"screeningType":{"type":"string","enum":["vision","hearing","scoliosis","bmi","blood_pressure"]},"performedOn":{"type":"string","format":"date"},"result":{"type":"object","additionalProperties":{}},"status":{"type":"string","enum":["normal","abnormal","inconclusive"]},"followupNeeded":{"type":"boolean"},"schoolId":{"type":"string","format":"uuid","nullable":true},"performedByUserId":{"type":"string","nullable":true},"gradeAtScreening":{"type":"string","nullable":true},"referralSentOn":{"type":"string","format":"date-time","nullable":true},"referralNotes":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","screeningType","performedOn","result","status","followupNeeded","schoolId","performedByUserId","gradeAtScreening","referralSentOn","referralNotes","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/incidents":{"get":{"summary":"List discipline incidents","tags":["Discipline"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["open","pending_review","closed"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"to","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentDate":{"type":"string","format":"date-time"},"location":{"type":"string","nullable":true},"offenseCode":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"}},"required":["id","incidentDate","location","offenseCode","description","status"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a discipline incident (emits IncidentReported)","tags":["Discipline"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"incidentDate":{"type":"string","format":"date-time"},"location":{"type":"string","maxLength":200},"offenseCode":{"type":"string","minLength":1,"maxLength":30},"description":{"type":"string","minLength":1,"maxLength":5000},"participants":{"type":"array","items":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["offender","victim","witness"]}},"required":["studentId","role"],"additionalProperties":false},"minItems":1,"maxItems":50},"hibBias":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":20},"hibBoardReport":{"type":"boolean"},"injuryLevel":{"type":"string","maxLength":30},"injuryDescription":{"type":"string","maxLength":500},"policeInvolved":{"type":"boolean"},"policeReportNumber":{"type":"string","maxLength":50},"witnessStatements":{"type":"string","maxLength":5000},"parentNotified":{"type":"boolean"},"notifyMethod":{"type":"string","maxLength":30},"notifyAt":{"type":"string","format":"date-time"},"notifyBy":{"type":"string","maxLength":200}},"required":["incidentDate","offenseCode","description","participants"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"incident":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentDate":{"type":"string","format":"date-time"},"location":{"type":"string","nullable":true},"offenseCode":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"}},"required":["id","incidentDate","location","offenseCode","description","status"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["incident","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/incidents/{id}":{"get":{"summary":"Get an incident with participants and actions","tags":["Discipline"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"incident":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentDate":{"type":"string","format":"date-time"},"location":{"type":"string","nullable":true},"offenseCode":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"}},"required":["id","incidentDate","location","offenseCode","description","status"],"additionalProperties":false},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["offender","victim","witness"]}},"required":["id","incidentId","studentPersonId","role"],"additionalProperties":false}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"actionType":{"type":"string"},"durationDays":{"type":"integer","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","incidentId","studentPersonId","actionType","durationDays","startDate","endDate","notes"],"additionalProperties":false}}},"required":["incident","participants","actions"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/incidents/{id}/actions":{"post":{"summary":"Assign a consequence (emits IncidentActionAssigned)","tags":["Discipline"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"actionType":{"type":"string","enum":["verbal_warning","detention","iss","oss","referral","expulsion_hearing","counseling","other"]},"durationDays":{"type":"integer","minimum":0,"maximum":365},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"notes":{"type":"string","maxLength":2000}},"required":["studentId","actionType"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"action":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"actionType":{"type":"string"},"durationDays":{"type":"integer","nullable":true},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","incidentId","studentPersonId","actionType","durationDays","startDate","endDate","notes"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["action","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hib/policy":{"get":{"summary":"Resolve the district's effective HIB policy (state default + district overrides).","tags":["Discipline"],"description":"Returns the policy code, deadline (school-days or calendar-days), recognized outcomes, bias categories, and notification checklist for the current district. When the district's state has no HIB statute, `disabled` is true and the feature is inert.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"disabled":{"type":"boolean"},"source":{"type":"string","enum":["district-override","state-default","fallback-generic"]},"usedFallback":{"type":"boolean"},"requestedCode":{"type":"string","nullable":true},"policy":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"jurisdiction":{"type":"string"},"specRef":{"type":"string"},"href":{"type":"string"},"description":{"type":"string"},"investigationDeadline":{"type":"object","properties":{"type":{"type":"string","enum":["school-days","calendar-days"]},"days":{"type":"integer"},"specRef":{"type":"string"}},"required":["type","days"],"additionalProperties":false},"outcomes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"triggersRemediation":{"type":"boolean"}},"required":["code","label","triggersRemediation"],"additionalProperties":false}},"biasCategories":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"statutory":{"type":"boolean"}},"required":["code","label","statutory"],"additionalProperties":false}},"notifications":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"dueWithin":{"type":"object","properties":{"type":{"type":"string","enum":["school-days","calendar-days"]},"days":{"type":"integer"}},"required":["type","days"],"additionalProperties":false},"audience":{"type":"string","enum":["parents-victim","parents-aggressor","board","superintendent","state"]}},"required":["code","label","audience"],"additionalProperties":false}},"reportingCadences":{"type":"array","items":{"type":"object","properties":{"audience":{"type":"string","enum":["board","state","public"]},"frequency":{"type":"string","enum":["monthly","quarterly","biannual","annual"]},"specRef":{"type":"string"},"description":{"type":"string"}},"required":["audience","frequency"],"additionalProperties":false}},"requiresSpecialist":{"type":"boolean"},"reviewedYear":{"type":"integer"}},"required":["code","name","jurisdiction","specRef","href","description","investigationDeadline","outcomes","biasCategories","notifications","reportingCadences","requiresSpecialist","reviewedYear"],"additionalProperties":false},"effectiveDeadline":{"type":"object","properties":{"type":{"type":"string","enum":["school-days","calendar-days"]},"days":{"type":"integer"},"specRef":{"type":"string"}},"required":["type","days"],"additionalProperties":false},"effectiveBiasCategories":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"statutory":{"type":"boolean"}},"required":["code","label","statutory"],"additionalProperties":false}}},"required":["disabled","source","usedFallback","requestedCode","policy","effectiveDeadline","effectiveBiasCategories"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/hib/policy/catalog":{"get":{"summary":"List all built-in HIB policies in the Forge catalog.","tags":["Discipline"],"description":"Surfaces every policy definition shipped with the product — the admin UI picker uses this to show the full option set to districts setting an override.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"policies":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"jurisdiction":{"type":"string"},"specRef":{"type":"string"},"href":{"type":"string"},"description":{"type":"string"},"investigationDeadline":{"type":"object","properties":{"type":{"type":"string","enum":["school-days","calendar-days"]},"days":{"type":"integer"},"specRef":{"type":"string"}},"required":["type","days"],"additionalProperties":false},"outcomes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"triggersRemediation":{"type":"boolean"}},"required":["code","label","triggersRemediation"],"additionalProperties":false}},"biasCategories":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"statutory":{"type":"boolean"}},"required":["code","label","statutory"],"additionalProperties":false}},"notifications":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"dueWithin":{"type":"object","properties":{"type":{"type":"string","enum":["school-days","calendar-days"]},"days":{"type":"integer"}},"required":["type","days"],"additionalProperties":false},"audience":{"type":"string","enum":["parents-victim","parents-aggressor","board","superintendent","state"]}},"required":["code","label","audience"],"additionalProperties":false}},"reportingCadences":{"type":"array","items":{"type":"object","properties":{"audience":{"type":"string","enum":["board","state","public"]},"frequency":{"type":"string","enum":["monthly","quarterly","biannual","annual"]},"specRef":{"type":"string"},"description":{"type":"string"}},"required":["audience","frequency"],"additionalProperties":false}},"requiresSpecialist":{"type":"boolean"},"reviewedYear":{"type":"integer"}},"required":["code","name","jurisdiction","specRef","href","description","investigationDeadline","outcomes","biasCategories","notifications","reportingCadences","requiresSpecialist","reviewedYear"],"additionalProperties":false}}},"required":["policies"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/hib-investigations":{"get":{"summary":"List HIB investigations","tags":["Discipline"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["open","completed"]},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"investigatorId":{"type":"string","format":"uuid"},"deadline":{"type":"string","format":"date"},"status":{"type":"string"},"outcome":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","incidentId","investigatorId","deadline","status","outcome","documentUrl","completedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Open an HIB investigation against an existing incident (emits HibInvestigationOpened)","tags":["Discipline"],"description":"Deadline is computed from the district's resolved HIB policy — school-days when a district calendar feed is available, calendar-day approximation otherwise. `deadlineApproximate` on the response flags when the UI should warn that the deadline is an approximation.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"incidentId":{"type":"string","format":"uuid"},"investigatorId":{"type":"string","format":"uuid"}},"required":["incidentId","investigatorId"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"hib":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"investigatorId":{"type":"string","format":"uuid"},"deadline":{"type":"string","format":"date"},"status":{"type":"string"},"outcome":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","incidentId","investigatorId","deadline","status","outcome","documentUrl","completedAt"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"},"deadlineApproximate":{"type":"boolean"}},"required":["hib","eventId","deadlineApproximate"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hib-investigations/{id}":{"get":{"summary":"Get an HIB investigation","tags":["Discipline"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"investigatorId":{"type":"string","format":"uuid"},"deadline":{"type":"string","format":"date"},"status":{"type":"string"},"outcome":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","incidentId","investigatorId","deadline","status","outcome","documentUrl","completedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hib-investigations/{id}/complete":{"post":{"summary":"Close an HIB investigation (emits HibInvestigationCompleted)","tags":["Discipline"],"description":"The outcome must be one recognized by the district's resolved HIB policy. Unknown outcomes return a 422 with the list of valid codes.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","minLength":1,"maxLength":40},"documentUrl":{"type":"string","format":"uri"}},"required":["outcome"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"hib":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"investigatorId":{"type":"string","format":"uuid"},"deadline":{"type":"string","format":"date"},"status":{"type":"string"},"outcome":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","incidentId","investigatorId","deadline","status","outcome","documentUrl","completedAt"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["hib","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/restraint-seclusion":{"post":{"summary":"Log a restraint or seclusion event (emits RestraintSeclusionLogged)","tags":["Discipline"],"description":"NJ-reportable event; the audit log retains this record indefinitely. Witnesses are recorded as person ids.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["physical_restraint","seclusion","mechanical_restraint"]},"durationSeconds":{"type":"integer","minimum":1,"maximum":86400},"witnesses":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":0,"maxItems":20},"notes":{"type":"string","maxLength":2000}},"required":["studentId","type","durationSeconds","witnesses"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"}},"required":["eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/incidents/{id}/escalations":{"get":{"summary":"List escalations for a discipline incident","tags":["Discipline"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"openedByPersonId":{"type":"string","format":"uuid","nullable":true},"openedAt":{"type":"string","format":"date-time"},"hearingScheduledAt":{"type":"string","format":"date-time","nullable":true},"hearingHeldAt":{"type":"string","format":"date-time","nullable":true},"hearingNotes":{"type":"string","nullable":true},"outcome":{"type":"string","enum":["pending","dismissed","sustained","expulsion_recommended"]},"sanctionType":{"type":"string","enum":["none","verbal_warning","suspension","expulsion","other"]},"suspensionDays":{"type":"integer","nullable":true},"expulsionRecommended":{"type":"boolean"},"returnDate":{"type":"string","format":"date","nullable":true},"parentNoticeIssuedAt":{"type":"string","format":"date-time","nullable":true},"parentNoticeMethod":{"type":"string","nullable":true},"appealDeadline":{"type":"string","format":"date","nullable":true},"appealFiledAt":{"type":"string","format":"date-time","nullable":true},"appealOutcome":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","incidentId","openedByPersonId","openedAt","hearingScheduledAt","hearingHeldAt","hearingNotes","outcome","sanctionType","suspensionDays","expulsionRecommended","returnDate","parentNoticeIssuedAt","parentNoticeMethod","appealDeadline","appealFiledAt","appealOutcome","notes","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Open a formal escalation for an incident (emits DisciplineEscalationOpened)","tags":["Discipline"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","maxLength":5000},"hearingScheduledAt":{"type":"string","format":"date-time"},"appealDeadline":{"type":"string","format":"date"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"openedByPersonId":{"type":"string","format":"uuid","nullable":true},"openedAt":{"type":"string","format":"date-time"},"hearingScheduledAt":{"type":"string","format":"date-time","nullable":true},"hearingHeldAt":{"type":"string","format":"date-time","nullable":true},"hearingNotes":{"type":"string","nullable":true},"outcome":{"type":"string","enum":["pending","dismissed","sustained","expulsion_recommended"]},"sanctionType":{"type":"string","enum":["none","verbal_warning","suspension","expulsion","other"]},"suspensionDays":{"type":"integer","nullable":true},"expulsionRecommended":{"type":"boolean"},"returnDate":{"type":"string","format":"date","nullable":true},"parentNoticeIssuedAt":{"type":"string","format":"date-time","nullable":true},"parentNoticeMethod":{"type":"string","nullable":true},"appealDeadline":{"type":"string","format":"date","nullable":true},"appealFiledAt":{"type":"string","format":"date-time","nullable":true},"appealOutcome":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","incidentId","openedByPersonId","openedAt","hearingScheduledAt","hearingHeldAt","hearingNotes","outcome","sanctionType","suspensionDays","expulsionRecommended","returnDate","parentNoticeIssuedAt","parentNoticeMethod","appealDeadline","appealFiledAt","appealOutcome","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/incidents/{id}/escalations/{escId}":{"patch":{"summary":"Update an escalation — schedule/hold hearing, record outcome, set sanction","tags":["Discipline"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"hearingScheduledAt":{"type":"string","format":"date-time"},"hearingHeldAt":{"type":"string","format":"date-time"},"hearingNotes":{"type":"string","maxLength":5000},"outcome":{"type":"string","enum":["pending","dismissed","sustained","expulsion_recommended"]},"sanctionType":{"type":"string","enum":["none","verbal_warning","suspension","expulsion","other"]},"suspensionDays":{"type":"integer","minimum":0,"maximum":365},"expulsionRecommended":{"type":"boolean"},"returnDate":{"type":"string","format":"date"},"notes":{"type":"string","maxLength":5000},"appealDeadline":{"type":"string","format":"date"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"escId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"openedByPersonId":{"type":"string","format":"uuid","nullable":true},"openedAt":{"type":"string","format":"date-time"},"hearingScheduledAt":{"type":"string","format":"date-time","nullable":true},"hearingHeldAt":{"type":"string","format":"date-time","nullable":true},"hearingNotes":{"type":"string","nullable":true},"outcome":{"type":"string","enum":["pending","dismissed","sustained","expulsion_recommended"]},"sanctionType":{"type":"string","enum":["none","verbal_warning","suspension","expulsion","other"]},"suspensionDays":{"type":"integer","nullable":true},"expulsionRecommended":{"type":"boolean"},"returnDate":{"type":"string","format":"date","nullable":true},"parentNoticeIssuedAt":{"type":"string","format":"date-time","nullable":true},"parentNoticeMethod":{"type":"string","nullable":true},"appealDeadline":{"type":"string","format":"date","nullable":true},"appealFiledAt":{"type":"string","format":"date-time","nullable":true},"appealOutcome":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","incidentId","openedByPersonId","openedAt","hearingScheduledAt","hearingHeldAt","hearingNotes","outcome","sanctionType","suspensionDays","expulsionRecommended","returnDate","parentNoticeIssuedAt","parentNoticeMethod","appealDeadline","appealFiledAt","appealOutcome","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/incidents/{id}/escalations/{escId}/notice":{"post":{"summary":"Record that a parent notice was issued (emits EscalationNoticeIssued)","tags":["Discipline"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"noticeMethod":{"type":"string","enum":["letter","phone","email","portal"]},"issuedAt":{"type":"string","format":"date-time"}},"required":["noticeMethod"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"escId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"openedByPersonId":{"type":"string","format":"uuid","nullable":true},"openedAt":{"type":"string","format":"date-time"},"hearingScheduledAt":{"type":"string","format":"date-time","nullable":true},"hearingHeldAt":{"type":"string","format":"date-time","nullable":true},"hearingNotes":{"type":"string","nullable":true},"outcome":{"type":"string","enum":["pending","dismissed","sustained","expulsion_recommended"]},"sanctionType":{"type":"string","enum":["none","verbal_warning","suspension","expulsion","other"]},"suspensionDays":{"type":"integer","nullable":true},"expulsionRecommended":{"type":"boolean"},"returnDate":{"type":"string","format":"date","nullable":true},"parentNoticeIssuedAt":{"type":"string","format":"date-time","nullable":true},"parentNoticeMethod":{"type":"string","nullable":true},"appealDeadline":{"type":"string","format":"date","nullable":true},"appealFiledAt":{"type":"string","format":"date-time","nullable":true},"appealOutcome":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","incidentId","openedByPersonId","openedAt","hearingScheduledAt","hearingHeldAt","hearingNotes","outcome","sanctionType","suspensionDays","expulsionRecommended","returnDate","parentNoticeIssuedAt","parentNoticeMethod","appealDeadline","appealFiledAt","appealOutcome","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/incidents/{id}/escalations/{escId}/appeal":{"post":{"summary":"File a family appeal of the escalation outcome (emits DisciplineAppealFiled)","tags":["Discipline"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"appealDeadline":{"type":"string","format":"date"},"notes":{"type":"string","maxLength":2000}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"escId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"openedByPersonId":{"type":"string","format":"uuid","nullable":true},"openedAt":{"type":"string","format":"date-time"},"hearingScheduledAt":{"type":"string","format":"date-time","nullable":true},"hearingHeldAt":{"type":"string","format":"date-time","nullable":true},"hearingNotes":{"type":"string","nullable":true},"outcome":{"type":"string","enum":["pending","dismissed","sustained","expulsion_recommended"]},"sanctionType":{"type":"string","enum":["none","verbal_warning","suspension","expulsion","other"]},"suspensionDays":{"type":"integer","nullable":true},"expulsionRecommended":{"type":"boolean"},"returnDate":{"type":"string","format":"date","nullable":true},"parentNoticeIssuedAt":{"type":"string","format":"date-time","nullable":true},"parentNoticeMethod":{"type":"string","nullable":true},"appealDeadline":{"type":"string","format":"date","nullable":true},"appealFiledAt":{"type":"string","format":"date-time","nullable":true},"appealOutcome":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","incidentId","openedByPersonId","openedAt","hearingScheduledAt","hearingHeldAt","hearingNotes","outcome","sanctionType","suspensionDays","expulsionRecommended","returnDate","parentNoticeIssuedAt","parentNoticeMethod","appealDeadline","appealFiledAt","appealOutcome","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Record the appeal decision (emits DisciplineAppealDecided)","tags":["Discipline"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"appealOutcome":{"type":"string","enum":["affirmed","reversed","withdrawn"]},"notes":{"type":"string","maxLength":2000}},"required":["appealOutcome"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"escId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"incidentId":{"type":"string","format":"uuid"},"openedByPersonId":{"type":"string","format":"uuid","nullable":true},"openedAt":{"type":"string","format":"date-time"},"hearingScheduledAt":{"type":"string","format":"date-time","nullable":true},"hearingHeldAt":{"type":"string","format":"date-time","nullable":true},"hearingNotes":{"type":"string","nullable":true},"outcome":{"type":"string","enum":["pending","dismissed","sustained","expulsion_recommended"]},"sanctionType":{"type":"string","enum":["none","verbal_warning","suspension","expulsion","other"]},"suspensionDays":{"type":"integer","nullable":true},"expulsionRecommended":{"type":"boolean"},"returnDate":{"type":"string","format":"date","nullable":true},"parentNoticeIssuedAt":{"type":"string","format":"date-time","nullable":true},"parentNoticeMethod":{"type":"string","nullable":true},"appealDeadline":{"type":"string","format":"date","nullable":true},"appealFiledAt":{"type":"string","format":"date-time","nullable":true},"appealOutcome":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","incidentId","openedByPersonId","openedAt","hearingScheduledAt","hearingHeldAt","hearingNotes","outcome","sanctionType","suspensionDays","expulsionRecommended","returnDate","parentNoticeIssuedAt","parentNoticeMethod","appealDeadline","appealFiledAt","appealOutcome","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/messages":{"get":{"summary":"List messages sent from this district","tags":["Communications"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["email","sms","push","voice"]},"in":"query","name":"channel","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"type":"string"},"templateId":{"type":"string","nullable":true},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"sentAt":{"type":"string","format":"date-time","nullable":true},"recipientCount":{"type":"integer"},"deliveryStatus":{"type":"object","additionalProperties":{}}},"required":["id","channel","templateId","subject","body","sentAt","recipientCount","deliveryStatus"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Send a message (one-to-many) via the worker (emits CommunicationSent)","tags":["Communications"],"description":"Records a row in `communications`, enqueues a send-notification job, and emits CommunicationSent. Actual delivery happens in the notifications worker; check delivery status via GET /v1/messages/:id.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["email","sms","push","voice"]},"subject":{"type":"string","maxLength":300},"body":{"type":"string","minLength":1,"maxLength":20000},"templateId":{"type":"string","format":"uuid"},"recipients":{"type":"array","items":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":30},"displayName":{"type":"string","maxLength":200}},"additionalProperties":false},"minItems":1,"maxItems":1000},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200}},"required":["channel","body","recipients"],"additionalProperties":false}}},"required":true},"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"messageId":{"type":"string","format":"uuid"},"queued":{"type":"integer"},"eventId":{"type":"string","format":"uuid"}},"required":["messageId","queued","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/broadcasts":{"post":{"summary":"Emergency or district-wide broadcast to a named audience","tags":["Communications"],"description":"Resolves the audience to a recipient list at send time, records one Communication row, enqueues the notification job, and emits CommunicationSent. Requires broadcast.send permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["email","sms","push","voice"]},"subject":{"type":"string","maxLength":300},"body":{"type":"string","minLength":1,"maxLength":20000},"audience":{"type":"string","enum":["all_guardians","all_staff","all_students","by_grade","by_school"]},"priority":{"type":"string","enum":["normal","high","urgent"],"default":"normal"},"sendMode":{"type":"string","enum":["now","scheduled"],"default":"now"},"scheduledFor":{"type":"string","format":"date-time"},"requireAck":{"type":"boolean","default":false},"targetGrade":{"type":"string","maxLength":10},"targetSchool":{"type":"string","format":"uuid"},"includeGuardians":{"type":"boolean","default":true},"includeStudents":{"type":"boolean","default":false},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200}},"required":["channel","body","audience"],"additionalProperties":false}}},"required":true},"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"messageId":{"type":"string","format":"uuid"},"queued":{"type":"integer"},"eventId":{"type":"string","format":"uuid"}},"required":["messageId","queued","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/templates":{"get":{"summary":"List message templates","tags":["Communications"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["email","sms","push","voice"]},"in":"query","name":"channel","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"channel":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"placeholders":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"}},"required":["id","code","name","channel","subject","body","placeholders","isActive"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a message template","tags":["Communications"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":100},"name":{"type":"string","minLength":1,"maxLength":200},"channel":{"type":"string","enum":["email","sms","push","voice"]},"subject":{"type":"string","maxLength":300},"body":{"type":"string","minLength":1,"maxLength":20000},"placeholders":{"type":"array","items":{"type":"string","maxLength":50},"default":[]},"isActive":{"type":"boolean","default":true}},"required":["code","name","channel","body"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"channel":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"placeholders":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"}},"required":["id","code","name","channel","subject","body","placeholders","isActive"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/templates/{id}":{"get":{"summary":"Get a message template","tags":["Communications"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"channel":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"placeholders":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"}},"required":["id","code","name","channel","subject","body","placeholders","isActive"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a message template","tags":["Communications"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"channel":{"type":"string","enum":["email","sms","push","voice"]},"subject":{"type":"string","maxLength":300},"body":{"type":"string","minLength":1,"maxLength":20000},"placeholders":{"type":"array","items":{"type":"string","maxLength":50},"default":[]},"isActive":{"type":"boolean","default":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"channel":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"placeholders":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"}},"required":["id","code","name","channel","subject","body","placeholders","isActive"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/comms/settings":{"get":{"summary":"Get communications provider settings (masked — no credentials returned)","tags":["Communications"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"emailProvider":{"type":"object","properties":{"name":{"type":"string"},"configured":{"type":"boolean"},"fromEmail":{"type":"string"},"fromName":{"type":"string"},"webhookToken":{"type":"string","format":"uuid"}},"required":["name","configured"],"additionalProperties":false},"smsProvider":{"type":"object","properties":{"name":{"type":"string"},"configured":{"type":"boolean"},"fromNumber":{"type":"string"}},"required":["name","configured"],"additionalProperties":false},"suppressionCount":{"type":"integer"}},"required":["emailProvider","smsProvider","suppressionCount"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update email / SMS provider configuration","tags":["Communications"],"description":"Writes email and/or SMS provider credentials into District.settings.comms. Credentials (API keys, auth tokens) are write-only — omit them to keep existing values unchanged. A webhook token is generated automatically for SendGrid on first save.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"emailProvider":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","enum":["sendgrid"]},"apiKey":{"type":"string","minLength":1},"fromEmail":{"type":"string","format":"email"},"fromName":{"type":"string","maxLength":100}},"required":["name","fromEmail"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","enum":["none"]}},"required":["name"],"additionalProperties":false}]},"smsProvider":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","enum":["twilio"]},"accountSid":{"type":"string","minLength":1},"authToken":{"type":"string","minLength":1},"fromNumber":{"type":"string","minLength":1}},"required":["name","fromNumber"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","enum":["none"]}},"required":["name"],"additionalProperties":false}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"emailProvider":{"type":"object","properties":{"name":{"type":"string"},"configured":{"type":"boolean"},"fromEmail":{"type":"string"},"fromName":{"type":"string"},"webhookToken":{"type":"string","format":"uuid"}},"required":["name","configured"],"additionalProperties":false},"smsProvider":{"type":"object","properties":{"name":{"type":"string"},"configured":{"type":"boolean"},"fromNumber":{"type":"string"}},"required":["name","configured"],"additionalProperties":false},"suppressionCount":{"type":"integer"}},"required":["emailProvider","smsProvider","suppressionCount"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/comms/settings/suppressions":{"delete":{"summary":"Clear the bounce/unsubscribe suppression list (or remove one address)","tags":["Communications"],"parameters":[{"schema":{"type":"string","format":"email"},"in":"query","name":"address","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"removed":{"type":"integer"}},"required":["removed"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/webhooks/sendgrid/{districtId}":{"post":{"tags":["Webhooks"],"description":"SendGrid delivery webhook (token-authed via ?tok=).","parameters":[{"schema":{"type":"string"},"in":"path","name":"districtId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/webhooks/twilio/{districtId}":{"post":{"tags":["Webhooks"],"description":"Twilio status webhook (HMAC-SHA1 authed).","parameters":[{"schema":{"type":"string"},"in":"path","name":"districtId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/compliance/rules":{"get":{"summary":"List the compliance rules available to this district","tags":["Compliance"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"integer"},"jurisdiction":{"type":"string"},"category":{"type":"string"},"specRef":{"type":"string"},"severity":{"type":"string","enum":["info","warn","blocker"]},"description":{"type":"string"}},"required":["id","version","jurisdiction","category","specRef","severity","description"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/compliance/rules/run":{"post":{"summary":"Evaluate all NJ rules against current district state","tags":["Compliance"],"description":"Runs every rule in the NJ rule set and returns a consolidated report of findings grouped by severity and rule id.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"districtId":{"type":"string","format":"uuid"},"asOf":{"type":"string","format":"date-time"},"findingsBySeverity":{"type":"object","properties":{"info":{"type":"integer"},"warn":{"type":"integer"},"blocker":{"type":"integer"}},"required":["info","warn","blocker"],"additionalProperties":false},"findingsByRule":{"type":"object","additionalProperties":{"type":"integer"}},"findings":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"ruleVersion":{"type":"integer"},"severity":{"type":"string","enum":["info","warn","blocker"]},"subjectType":{"type":"string"},"subjectId":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["ruleId","ruleVersion","severity","subjectType","subjectId","message"],"additionalProperties":false}}},"required":["districtId","asOf","findingsBySeverity","findingsByRule","findings"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/compliance/smids/missing":{"get":{"summary":"List active students without a SMID","tags":["Compliance"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","smid"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/compliance/smids/{id}":{"post":{"summary":"Assign a SMID to a student","tags":["Compliance"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"smid":{"type":"string","pattern":"^(?:\\d{10}|NJ\\d{8})$"}},"required":["smid"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","smid"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/compliance/smids/generate-missing":{"post":{"summary":"Generate placeholder SMIDs for every active student without one","tags":["Compliance"],"description":"Uses a deterministic `NJ########` prefix. These are placeholders until the official NJSMART-issued SMIDs are imported. Safe to re-run — only assigns where smid is currently null.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"generated":{"type":"integer","minimum":0},"assignments":{"type":"array","items":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"smid":{"type":"string"}},"required":["studentId","smid"],"additionalProperties":false}}},"required":["generated","assignments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/compliance/reports":{"get":{"summary":"List generated state reports","tags":["Compliance"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string"},"in":"query","name":"reportType","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"reportType":{"type":"string"},"period":{"type":"string"},"status":{"type":"string"},"generatedAt":{"type":"string","format":"date-time","nullable":true},"submittedAt":{"type":"string","format":"date-time","nullable":true},"dueDate":{"type":"string","format":"date","nullable":true},"summary":{"type":"object","additionalProperties":{}}},"required":["id","reportType","period","status","generatedAt","submittedAt","dueDate","summary"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/compliance/reports/available":{"get":{"summary":"List state-report adapters available for the calling district","tags":["Compliance"],"description":"Reads the district's state code and returns the registered adapters for that state. Used by the admin UI to render generation buttons dynamically.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"stateCode":{"type":"string","nullable":true},"adapters":{"type":"array","items":{"type":"object","properties":{"stateCode":{"type":"string"},"reportType":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["stateCode","reportType","label"],"additionalProperties":false}}},"required":["stateCode","adapters"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/compliance/smids/audit":{"get":{"summary":"Audit SMID coverage for the calling district","tags":["Compliance"],"description":"Returns counts of students on placeholder (NJ########) IDs and students with no SMID. Used by the UI to show a \"ready to submit\" badge and by the strict-generation flow to block submission.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"totalActive":{"type":"integer"},"placeholderCount":{"type":"integer"},"missingCount":{"type":"integer"},"placeholderSampleIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["totalActive","placeholderCount","missingCount","placeholderSampleIds"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/compliance/reports/{id}":{"get":{"summary":"Get a state-report record","tags":["Compliance"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"reportType":{"type":"string"},"period":{"type":"string"},"status":{"type":"string"},"generatedAt":{"type":"string","format":"date-time","nullable":true},"submittedAt":{"type":"string","format":"date-time","nullable":true},"dueDate":{"type":"string","format":"date","nullable":true},"summary":{"type":"object","additionalProperties":{}}},"required":["id","reportType","period","status","generatedAt","submittedAt","dueDate","summary"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/compliance/instructional-time":{"get":{"summary":"Per-school instructional-time breakdown","tags":["Compliance"],"description":"Evaluates the INSTRUCTIONAL_TIME_RULE and returns the per-school breakdown the rule computed: days counted, days projected, minutes counted, minutes projected, short-day list, findings. Designed for the drill-down dashboard.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"schoolYearName":{"type":"string","nullable":true},"stateCode":{"type":"string","nullable":true},"stateMinDays":{"type":"integer","nullable":true},"stateMinMinutes":{"type":"integer","nullable":true},"policy":{"type":"object","properties":{"defaultDailyMinutes":{"type":"integer","nullable":true},"minDailyMinutesForCount":{"type":"integer","nullable":true},"warnBufferDays":{"type":"integer","nullable":true},"maxDaysCeiling":{"type":"integer","nullable":true},"minDaysOverride":{"type":"integer","nullable":true}},"required":["defaultDailyMinutes","minDailyMinutesForCount","warnBufferDays","maxDaysCeiling","minDaysOverride"],"additionalProperties":false},"schools":{"type":"array","items":{"type":"object","properties":{"schoolId":{"type":"string","format":"uuid"},"schoolName":{"type":"string"},"daysCountedSoFar":{"type":"integer"},"daysProjectedFullYear":{"type":"integer"},"minutesCountedSoFar":{"type":"integer"},"minutesProjectedFullYear":{"type":"integer"},"remainingScheduledDays":{"type":"integer"},"shortDays":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"scheduledMinutes":{"type":"integer"},"reason":{"type":"string","nullable":true}},"required":["date","scheduledMinutes","reason"],"additionalProperties":false}},"findings":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"ruleVersion":{"type":"integer"},"severity":{"type":"string","enum":["info","warn","blocker"]},"subjectType":{"type":"string"},"subjectId":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["ruleId","ruleVersion","severity","subjectType","subjectId","message"],"additionalProperties":false}}},"required":["schoolId","schoolName","daysCountedSoFar","daysProjectedFullYear","minutesCountedSoFar","minutesProjectedFullYear","remainingScheduledDays","shortDays","findings"],"additionalProperties":false}}},"required":["asOf","schoolYearId","schoolYearName","stateCode","stateMinDays","stateMinMinutes","policy","schools"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/districts/instructional-time-policy":{"get":{"summary":"Read the district instructional-time policy","tags":["District"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"defaultDailyMinutes":{"type":"integer","minimum":0,"maximum":720,"nullable":true},"minDailyMinutesForCount":{"type":"integer","minimum":0,"maximum":720,"nullable":true},"warnBufferDays":{"type":"integer","minimum":0,"maximum":60,"nullable":true},"maxDaysCeiling":{"type":"integer","minimum":0,"maximum":366,"nullable":true},"minDaysOverride":{"type":"integer","minimum":0,"maximum":366,"nullable":true}},"required":["defaultDailyMinutes","minDailyMinutesForCount","warnBufferDays","maxDaysCeiling","minDaysOverride"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update the district instructional-time policy","tags":["District"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"defaultDailyMinutes":{"type":"integer","minimum":0,"maximum":720,"nullable":true},"minDailyMinutesForCount":{"type":"integer","minimum":0,"maximum":720,"nullable":true},"warnBufferDays":{"type":"integer","minimum":0,"maximum":60,"nullable":true},"maxDaysCeiling":{"type":"integer","minimum":0,"maximum":366,"nullable":true},"minDaysOverride":{"type":"integer","minimum":0,"maximum":366,"nullable":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"defaultDailyMinutes":{"type":"integer","minimum":0,"maximum":720,"nullable":true},"minDailyMinutesForCount":{"type":"integer","minimum":0,"maximum":720,"nullable":true},"warnBufferDays":{"type":"integer","minimum":0,"maximum":60,"nullable":true},"maxDaysCeiling":{"type":"integer","minimum":0,"maximum":366,"nullable":true},"minDaysOverride":{"type":"integer","minimum":0,"maximum":366,"nullable":true}},"required":["defaultDailyMinutes","minDailyMinutesForCount","warnBufferDays","maxDaysCeiling","minDaysOverride"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/migration/preview/genesis":{"post":{"summary":"Preview a Genesis CSV migration (read-only — no writes)","tags":["Migration"],"description":"Paste students.csv, guardians.csv (optional), and enrollments.csv from a Genesis 5 export. Returns row counts, warnings, and the first 10 students so the district can validate the mapping. Does NOT commit. To actually apply the migration, contact your Forge SIS account manager.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentsCsv":{"type":"string","minLength":1,"maxLength":50000000},"guardiansCsv":{"type":"string","maxLength":50000000},"enrollmentsCsv":{"type":"string","minLength":1,"maxLength":50000000}},"required":["studentsCsv","enrollmentsCsv"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"vendor":{"type":"string","enum":["genesis","powerschool","oneroster"]},"stats":{"type":"object","properties":{"personsCount":{"type":"integer"},"studentsCount":{"type":"integer"},"guardiansCount":{"type":"integer"},"staffCount":{"type":"integer"},"enrollmentsCount":{"type":"integer"},"guardianshipsCount":{"type":"integer"},"warningsCount":{"type":"integer"}},"required":["personsCount","studentsCount","guardiansCount","staffCount","enrollmentsCount","guardianshipsCount","warningsCount"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}},"sample":{"type":"object","properties":{"students":{"type":"array","items":{"type":"object","properties":{"localId":{"type":"string"},"smid":{"type":"string","nullable":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"dateOfBirth":{"type":"string","nullable":true},"gradeLevel":{"type":"string","nullable":true}},"required":["localId","smid","firstName","lastName","dateOfBirth","gradeLevel"],"additionalProperties":false}}},"required":["students"],"additionalProperties":false}},"required":["vendor","stats","warnings","sample"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/migration/preview/powerschool":{"post":{"summary":"Preview a PowerSchool CSV migration (read-only — no writes)","tags":["Migration"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentsCsv":{"type":"string","minLength":1,"maxLength":50000000},"guardiansCsv":{"type":"string","maxLength":50000000},"enrollmentsCsv":{"type":"string","minLength":1,"maxLength":50000000}},"required":["studentsCsv","enrollmentsCsv"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"vendor":{"type":"string","enum":["genesis","powerschool","oneroster"]},"stats":{"type":"object","properties":{"personsCount":{"type":"integer"},"studentsCount":{"type":"integer"},"guardiansCount":{"type":"integer"},"staffCount":{"type":"integer"},"enrollmentsCount":{"type":"integer"},"guardianshipsCount":{"type":"integer"},"warningsCount":{"type":"integer"}},"required":["personsCount","studentsCount","guardiansCount","staffCount","enrollmentsCount","guardianshipsCount","warningsCount"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}},"sample":{"type":"object","properties":{"students":{"type":"array","items":{"type":"object","properties":{"localId":{"type":"string"},"smid":{"type":"string","nullable":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"dateOfBirth":{"type":"string","nullable":true},"gradeLevel":{"type":"string","nullable":true}},"required":["localId","smid","firstName","lastName","dateOfBirth","gradeLevel"],"additionalProperties":false}}},"required":["students"],"additionalProperties":false}},"required":["vendor","stats","warnings","sample"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/migration/preview/oneroster":{"post":{"summary":"Preview a OneRoster CSV migration (read-only — no writes)","tags":["Migration"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"usersCsv":{"type":"string","minLength":1,"maxLength":50000000},"enrollmentsCsv":{"type":"string","minLength":1,"maxLength":50000000}},"required":["usersCsv","enrollmentsCsv"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"vendor":{"type":"string","enum":["genesis","powerschool","oneroster"]},"stats":{"type":"object","properties":{"personsCount":{"type":"integer"},"studentsCount":{"type":"integer"},"guardiansCount":{"type":"integer"},"staffCount":{"type":"integer"},"enrollmentsCount":{"type":"integer"},"guardianshipsCount":{"type":"integer"},"warningsCount":{"type":"integer"}},"required":["personsCount","studentsCount","guardiansCount","staffCount","enrollmentsCount","guardianshipsCount","warningsCount"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}},"sample":{"type":"object","properties":{"students":{"type":"array","items":{"type":"object","properties":{"localId":{"type":"string"},"smid":{"type":"string","nullable":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"dateOfBirth":{"type":"string","nullable":true},"gradeLevel":{"type":"string","nullable":true}},"required":["localId","smid","firstName","lastName","dateOfBirth","gradeLevel"],"additionalProperties":false}}},"required":["students"],"additionalProperties":false}},"required":["vendor","stats","warnings","sample"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/positions":{"get":{"summary":"List HR positions","tags":["Business Office"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"positionCode":{"type":"string"},"title":{"type":"string"},"budgetAccountId":{"type":"string","format":"uuid","nullable":true},"fteEquivalent":{"type":"number"},"certRequired":{"type":"array","items":{"type":"string"}},"description":{"type":"string","nullable":true},"employmentType":{"type":"string"},"bargainingUnit":{"type":"string","nullable":true},"reportingToTitle":{"type":"string","nullable":true},"workDays":{"type":"integer","nullable":true},"dailyHours":{"type":"number","nullable":true},"salaryRange":{"type":"object","properties":{"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true},"step":{"type":"string","nullable":true}},"required":["min","max","step"],"additionalProperties":false,"nullable":true},"isSupervisory":{"type":"boolean"},"isConfidential":{"type":"boolean"}},"required":["id","positionCode","title","budgetAccountId","fteEquivalent","certRequired","description","employmentType","bargainingUnit","reportingToTitle","workDays","dailyHours","salaryRange","isSupervisory","isConfidential"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create HR position","tags":["Business Office"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"positionCode":{"type":"string","minLength":1,"maxLength":50},"title":{"type":"string","minLength":1,"maxLength":200},"budgetAccountId":{"type":"string","format":"uuid"},"fteEquivalent":{"type":"number","minimum":0,"maximum":2,"default":1},"certRequired":{"type":"array","items":{"type":"string","maxLength":50},"default":[]},"description":{"type":"string","maxLength":4000},"employmentType":{"type":"string","enum":["certificated","classified","substitute","contract"],"default":"certificated"},"bargainingUnit":{"type":"string","maxLength":30},"reportingToTitle":{"type":"string","maxLength":200},"workDays":{"type":"integer","minimum":0,"maximum":260},"dailyHours":{"type":"number","minimum":0,"maximum":24},"salaryRange":{"type":"object","properties":{"min":{"type":"number","minimum":0},"max":{"type":"number","minimum":0},"step":{"type":"string","maxLength":60}},"additionalProperties":false},"isSupervisory":{"type":"boolean","default":false},"isConfidential":{"type":"boolean","default":false}},"required":["positionCode","title"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"positionCode":{"type":"string"},"title":{"type":"string"},"budgetAccountId":{"type":"string","format":"uuid","nullable":true},"fteEquivalent":{"type":"number"},"certRequired":{"type":"array","items":{"type":"string"}},"description":{"type":"string","nullable":true},"employmentType":{"type":"string"},"bargainingUnit":{"type":"string","nullable":true},"reportingToTitle":{"type":"string","nullable":true},"workDays":{"type":"integer","nullable":true},"dailyHours":{"type":"number","nullable":true},"salaryRange":{"type":"object","properties":{"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true},"step":{"type":"string","nullable":true}},"required":["min","max","step"],"additionalProperties":false,"nullable":true},"isSupervisory":{"type":"boolean"},"isConfidential":{"type":"boolean"}},"required":["id","positionCode","title","budgetAccountId","fteEquivalent","certRequired","description","employmentType","bargainingUnit","reportingToTitle","workDays","dailyHours","salaryRange","isSupervisory","isConfidential"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/positions/{id}":{"get":{"summary":"Get HR position","tags":["Business Office"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"positionCode":{"type":"string"},"title":{"type":"string"},"budgetAccountId":{"type":"string","format":"uuid","nullable":true},"fteEquivalent":{"type":"number"},"certRequired":{"type":"array","items":{"type":"string"}},"description":{"type":"string","nullable":true},"employmentType":{"type":"string"},"bargainingUnit":{"type":"string","nullable":true},"reportingToTitle":{"type":"string","nullable":true},"workDays":{"type":"integer","nullable":true},"dailyHours":{"type":"number","nullable":true},"salaryRange":{"type":"object","properties":{"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true},"step":{"type":"string","nullable":true}},"required":["min","max","step"],"additionalProperties":false,"nullable":true},"isSupervisory":{"type":"boolean"},"isConfidential":{"type":"boolean"}},"required":["id","positionCode","title","budgetAccountId","fteEquivalent","certRequired","description","employmentType","bargainingUnit","reportingToTitle","workDays","dailyHours","salaryRange","isSupervisory","isConfidential"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update HR position","tags":["Business Office"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"budgetAccountId":{"type":"string","format":"uuid"},"fteEquivalent":{"type":"number","minimum":0,"maximum":2,"default":1},"certRequired":{"type":"array","items":{"type":"string","maxLength":50},"default":[]},"description":{"type":"string","maxLength":4000},"employmentType":{"type":"string","enum":["certificated","classified","substitute","contract"],"default":"certificated"},"bargainingUnit":{"type":"string","maxLength":30},"reportingToTitle":{"type":"string","maxLength":200},"workDays":{"type":"integer","minimum":0,"maximum":260},"dailyHours":{"type":"number","minimum":0,"maximum":24},"salaryRange":{"type":"object","properties":{"min":{"type":"number","minimum":0},"max":{"type":"number","minimum":0},"step":{"type":"string","maxLength":60}},"additionalProperties":false},"isSupervisory":{"type":"boolean","default":false},"isConfidential":{"type":"boolean","default":false}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"positionCode":{"type":"string"},"title":{"type":"string"},"budgetAccountId":{"type":"string","format":"uuid","nullable":true},"fteEquivalent":{"type":"number"},"certRequired":{"type":"array","items":{"type":"string"}},"description":{"type":"string","nullable":true},"employmentType":{"type":"string"},"bargainingUnit":{"type":"string","nullable":true},"reportingToTitle":{"type":"string","nullable":true},"workDays":{"type":"integer","nullable":true},"dailyHours":{"type":"number","nullable":true},"salaryRange":{"type":"object","properties":{"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true},"step":{"type":"string","nullable":true}},"required":["min","max","step"],"additionalProperties":false,"nullable":true},"isSupervisory":{"type":"boolean"},"isConfidential":{"type":"boolean"}},"required":["id","positionCode","title","budgetAccountId","fteEquivalent","certRequired","description","employmentType","bargainingUnit","reportingToTitle","workDays","dailyHours","salaryRange","isSupervisory","isConfidential"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/payroll/cycles":{"get":{"summary":"List payroll cycles","tags":["Business Office"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["draft","processing","closed"]},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"periodStart":{"type":"string","format":"date"},"periodEnd":{"type":"string","format":"date"},"payDate":{"type":"string","format":"date"},"status":{"type":"string"}},"required":["id","periodStart","periodEnd","payDate","status"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a draft payroll cycle","tags":["Business Office"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"periodStart":{"type":"string","format":"date"},"periodEnd":{"type":"string","format":"date"},"payDate":{"type":"string","format":"date"}},"required":["periodStart","periodEnd","payDate"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"periodStart":{"type":"string","format":"date"},"periodEnd":{"type":"string","format":"date"},"payDate":{"type":"string","format":"date"},"status":{"type":"string"}},"required":["id","periodStart","periodEnd","payDate","status"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/payroll/cycles/{id}/entries":{"get":{"summary":"List entries for a payroll cycle","tags":["Business Office"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cycleId":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"grossPay":{"type":"number"},"netPay":{"type":"number"},"tpafContribution":{"type":"number"},"persContribution":{"type":"number"},"deductions":{"type":"object","additionalProperties":{"type":"number"}}},"required":["id","cycleId","staffPersonId","grossPay","netPay","tpafContribution","persContribution","deductions"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Add/update a payroll entry (auto-computes TPAF/PERS + net)","tags":["Business Office"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"staffPersonId":{"type":"string","format":"uuid"},"grossPay":{"type":"number","minimum":0,"maximum":1000000},"program":{"type":"string","enum":["TPAF","PERS","NONE"]},"planCode":{"type":"string","minLength":1,"maxLength":40},"employmentCategory":{"type":"string","enum":["certificated","classified","none"]},"hireDate":{"type":"string","format":"date"},"tierCode":{"type":"string","minLength":1,"maxLength":40},"ytdPayPrior":{"type":"number","minimum":0,"maximum":10000000},"deductions":{"type":"object","additionalProperties":{"type":"number","minimum":0},"default":{}}},"required":["staffPersonId","grossPay"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cycleId":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"grossPay":{"type":"number"},"netPay":{"type":"number"},"tpafContribution":{"type":"number"},"persContribution":{"type":"number"},"deductions":{"type":"object","additionalProperties":{"type":"number"}}},"required":["id","cycleId","staffPersonId","grossPay","netPay","tpafContribution","persContribution","deductions"],"additionalProperties":false},"resolvedPlanCode":{"type":"string","nullable":true},"tierCode":{"type":"string","nullable":true},"employeeRate":{"type":"number"},"employerContribution":{"type":"number","nullable":true},"employerRate":{"type":"number","nullable":true},"usedFallback":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["no-plan-resolved","state-config-legacy","plan-missing-rates"]},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}}},"required":["entry","resolvedPlanCode","tierCode","employeeRate","employerContribution","employerRate","usedFallback","warnings"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/payroll/cycles/{id}/actions/close":{"post":{"summary":"Close a payroll cycle (emits PayrollCycleClosed)","tags":["Business Office"],"description":"Marks the cycle final; no further entries can be added. Totals are computed at close time and stamped on the event.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"cycle":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"periodStart":{"type":"string","format":"date"},"periodEnd":{"type":"string","format":"date"},"payDate":{"type":"string","format":"date"},"status":{"type":"string"}},"required":["id","periodStart","periodEnd","payDate","status"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"},"grossTotal":{"type":"number"},"netTotal":{"type":"number"}},"required":["cycle","eventId","grossTotal","netTotal"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/retirement-plans":{"get":{"summary":"List retirement plans available in this district's state","tags":["Business Office"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"stateCode":{"type":"string","nullable":true},"isLegacy":{"type":"boolean"},"assignment":{"type":"object","properties":{"certificated":{"type":"string","nullable":true},"classified":{"type":"string","nullable":true}},"required":["certificated","classified"],"additionalProperties":false},"plans":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"fullName":{"type":"string"},"coverage":{"type":"string","enum":["certificated","classified","any"]},"employeeContribution":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["flat"]},"rates":{"type":"array","items":{"type":"object","properties":{"effectiveYear":{"type":"integer"},"rate":{"type":"number"},"note":{"type":"string"}},"required":["effectiveYear","rate"],"additionalProperties":false}}},"required":["type","rates"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["tiered"]},"tiers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"hiredBefore":{"type":"string"},"hiredOnOrAfter":{"type":"string"},"rates":{"type":"array","items":{"type":"object","properties":{"effectiveYear":{"type":"integer"},"rate":{"type":"number"},"note":{"type":"string"}},"required":["effectiveYear","rate"],"additionalProperties":false}},"note":{"type":"string"}},"required":["code","name","rates"],"additionalProperties":false}},"defaultTier":{"type":"string"}},"required":["type","tiers"],"additionalProperties":false}]},"employerContribution":{"type":"object","properties":{"rates":{"type":"array","items":{"type":"object","properties":{"effectiveYear":{"type":"integer"},"rate":{"type":"number"},"note":{"type":"string"}},"required":["effectiveYear","rate"],"additionalProperties":false}},"note":{"type":"string"}},"required":["rates"],"additionalProperties":false},"wageBaseCap":{"type":"object","properties":{"annualCap":{"type":"number"},"note":{"type":"string"}},"required":["annualCap"],"additionalProperties":false},"specRef":{"type":"string"},"description":{"type":"string"},"href":{"type":"string"}},"required":["code","fullName","coverage","employeeContribution"],"additionalProperties":false}}},"required":["stateCode","isLegacy","assignment","plans"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/retirement-plans/resolve":{"post":{"summary":"Dry-run a retirement-contribution calculation","tags":["Business Office"],"description":"Without writing a payroll entry, compute what the employee/employer contribution would be for a given gross, plan/category, and hire date. Used by the admin contribution tester and by bulk-import validators.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"grossPay":{"type":"number","minimum":0,"maximum":1000000},"year":{"type":"integer","minimum":1990,"maximum":2200},"planCode":{"type":"string","minLength":1,"maxLength":40},"employmentCategory":{"type":"string","enum":["certificated","classified","none"]},"hireDate":{"type":"string","format":"date"},"tierCode":{"type":"string","minLength":1,"maxLength":40},"ytdPayPrior":{"type":"number","minimum":0,"maximum":10000000},"deductions":{"type":"object","additionalProperties":{"type":"number","minimum":0},"default":{}}},"required":["grossPay"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"resolvedPlanCode":{"type":"string","nullable":true},"tierCode":{"type":"string","nullable":true},"gross":{"type":"number"},"net":{"type":"number"},"employeeContribution":{"type":"number"},"employeeRate":{"type":"number"},"employerContribution":{"type":"number","nullable":true},"employerRate":{"type":"number","nullable":true},"contributionBasis":{"type":"number"},"otherDeductions":{"type":"number"},"usedFallback":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["no-plan-resolved","state-config-legacy","plan-missing-rates"]},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}}},"required":["resolvedPlanCode","tierCode","gross","net","employeeContribution","employeeRate","employerContribution","employerRate","contributionBasis","otherDeductions","usedFallback","warnings"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/budget/accounts":{"get":{"summary":"List budget accounts","tags":["Business Office"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"integer"},"in":"query","name":"fiscalYear","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountCode":{"type":"string"},"description":{"type":"string"},"njCoaCode":{"type":"string","nullable":true},"fiscalYear":{"type":"integer"}},"required":["id","accountCode","description","njCoaCode","fiscalYear"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a budget account","tags":["Business Office"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"accountCode":{"type":"string","minLength":1,"maxLength":50},"description":{"type":"string","minLength":1,"maxLength":300},"njCoaCode":{"type":"string","maxLength":50},"fiscalYear":{"type":"integer","minimum":2000,"maximum":2100}},"required":["accountCode","description","fiscalYear"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountCode":{"type":"string"},"description":{"type":"string"},"njCoaCode":{"type":"string","nullable":true},"fiscalYear":{"type":"integer"}},"required":["id","accountCode","description","njCoaCode","fiscalYear"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/budget/entries":{"post":{"summary":"Post a budget journal entry","tags":["Business Office"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string","format":"uuid"},"entryType":{"type":"string","enum":["debit","credit","encumbrance","adjustment"]},"amount":{"type":"number"},"memo":{"type":"string","maxLength":500}},"required":["accountId","entryType","amount"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"entryType":{"type":"string"},"amount":{"type":"number"},"memo":{"type":"string","nullable":true},"postedAt":{"type":"string","format":"date-time"}},"required":["id","accountId","entryType","amount","memo","postedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/budget/summary":{"get":{"summary":"Budget summary by account for a fiscal year","tags":["Business Office"],"parameters":[{"schema":{"type":"integer","minimum":2000,"maximum":2100},"in":"query","name":"fiscalYear","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fiscalYear":{"type":"integer"},"totalsByAccount":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string","format":"uuid"},"accountCode":{"type":"string"},"description":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"encumbrance":{"type":"number"},"balance":{"type":"number"}},"required":["accountId","accountCode","description","debit","credit","encumbrance","balance"],"additionalProperties":false}}},"required":["fiscalYear","totalsByAccount"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluations":{"get":{"summary":"List staff evaluations","tags":["Business Office"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"staffId","required":false},{"schema":{"type":"string"},"in":"query","name":"cycleName","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"cycleName":{"type":"string"},"frameworkCode":{"type":"string"},"status":{"type":"string"},"observations":{"type":"array","items":{"type":"object","additionalProperties":{}}},"sgoPlan":{"type":"object","additionalProperties":{},"nullable":true},"finalScore":{"type":"number","nullable":true}},"required":["id","staffPersonId","cycleName","frameworkCode","status","observations","sgoPlan","finalScore"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Open an evaluation cycle for a staff member","tags":["Business Office"],"description":"Framework defaults to the district's resolved evaluation framework (state default or district override). Pass `frameworkCode` explicitly to pin a cycle to a specific rubric.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"staffPersonId":{"type":"string","format":"uuid"},"cycleName":{"type":"string","minLength":1,"maxLength":100},"frameworkCode":{"type":"string","minLength":1,"maxLength":60}},"required":["staffPersonId","cycleName"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"cycleName":{"type":"string"},"frameworkCode":{"type":"string"},"status":{"type":"string"},"observations":{"type":"array","items":{"type":"object","additionalProperties":{}}},"sgoPlan":{"type":"object","additionalProperties":{},"nullable":true},"finalScore":{"type":"number","nullable":true}},"required":["id","staffPersonId","cycleName","frameworkCode","status","observations","sgoPlan","finalScore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluations/{id}":{"get":{"summary":"Get an evaluation","tags":["Business Office"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"cycleName":{"type":"string"},"frameworkCode":{"type":"string"},"status":{"type":"string"},"observations":{"type":"array","items":{"type":"object","additionalProperties":{}}},"sgoPlan":{"type":"object","additionalProperties":{},"nullable":true},"finalScore":{"type":"number","nullable":true}},"required":["id","staffPersonId","cycleName","frameworkCode","status","observations","sgoPlan","finalScore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluations/{id}/observations":{"post":{"summary":"Append an observation to an evaluation","tags":["Business Office"],"description":"Validates the observation against the cycle's framework. Unknown domains, out-of-range scores, and off-step scores return 422 with structured issues rather than silently storing garbage.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"observedAt":{"type":"string","format":"date-time"},"observerPersonId":{"type":"string","format":"uuid"},"domain":{"type":"string","minLength":1,"maxLength":60},"score":{"type":"number"},"notes":{"type":"string","maxLength":5000},"durationMinutes":{"type":"integer","minimum":0,"maximum":600},"announced":{"type":"boolean"}},"required":["observedAt","observerPersonId","domain","score"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"cycleName":{"type":"string"},"frameworkCode":{"type":"string"},"status":{"type":"string"},"observations":{"type":"array","items":{"type":"object","additionalProperties":{}}},"sgoPlan":{"type":"object","additionalProperties":{},"nullable":true},"finalScore":{"type":"number","nullable":true}},"required":["id","staffPersonId","cycleName","frameworkCode","status","observations","sgoPlan","finalScore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["unknown-domain","score-out-of-range","score-not-on-step","score-not-in-categorical-values","duration-out-of-range"]},"message":{"type":"string"},"path":{"type":"string"}},"required":["code","message","path"],"additionalProperties":false}}},"required":["issues"],"additionalProperties":false},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluations/{id}/sgo":{"post":{"summary":"Set the SGO plan on an evaluation","tags":["Business Office"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sgoPlan":{"type":"object","additionalProperties":{}}},"required":["sgoPlan"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"cycleName":{"type":"string"},"frameworkCode":{"type":"string"},"status":{"type":"string"},"observations":{"type":"array","items":{"type":"object","additionalProperties":{}}},"sgoPlan":{"type":"object","additionalProperties":{},"nullable":true},"finalScore":{"type":"number","nullable":true}},"required":["id","staffPersonId","cycleName","frameworkCode","status","observations","sgoPlan","finalScore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluations/{id}/complete":{"post":{"summary":"Close an evaluation with a final score (emits EvaluationCompleted)","tags":["Business Office"],"description":"Auto-computes the summative score from observations + SGO using the cycle's framework. If the caller supplies `finalScore`, that value is persisted; otherwise the computed score is used. The scoring breakdown (per-domain averages, warnings, summative rating band) is always returned alongside.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"finalScore":{"type":"number","minimum":0,"maximum":5},"studentGrowthScore":{"type":"number","minimum":0,"maximum":5}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"evaluation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"cycleName":{"type":"string"},"frameworkCode":{"type":"string"},"status":{"type":"string"},"observations":{"type":"array","items":{"type":"object","additionalProperties":{}}},"sgoPlan":{"type":"object","additionalProperties":{},"nullable":true},"finalScore":{"type":"number","nullable":true}},"required":["id","staffPersonId","cycleName","frameworkCode","status","observations","sgoPlan","finalScore"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"},"scoring":{"type":"object","properties":{"practiceScore":{"type":"number","nullable":true},"studentGrowthScore":{"type":"number","nullable":true},"finalScore":{"type":"number","nullable":true},"summativeRating":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"minScore":{"type":"number"},"maxScore":{"type":"number"}},"required":["code","label","minScore","maxScore"],"additionalProperties":false,"nullable":true},"domainBreakdown":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"averageScore":{"type":"number"},"weight":{"type":"number"},"observationCount":{"type":"number"}},"required":["code","averageScore","weight","observationCount"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["below-required-observations","below-required-announced","below-required-unannounced","below-required-total-minutes","missing-student-growth","no-observations"]},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}}},"required":["practiceScore","studentGrowthScore","finalScore","summativeRating","domainBreakdown","warnings"],"additionalProperties":false}},"required":["evaluation","eventId","scoring"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluation-framework":{"get":{"summary":"Resolve the teacher evaluation framework for this district","tags":["Business Office"],"description":"Returns the framework currently applied to this district: district override if set, otherwise the state default, otherwise the generic fallback. Observation scores for all open cycles should match this framework.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"framework":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"jurisdiction":{"type":"string","enum":["NJ","CA","TX","NY","FL","IL","PA","multi-state","generic"]},"audience":{"type":"string","enum":["teacher","leader","any"]},"specRef":{"type":"string"},"href":{"type":"string"},"description":{"type":"string"},"domains":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"weight":{"type":"number"},"components":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"required":["code","name"],"additionalProperties":false}}},"required":["code","name"],"additionalProperties":false}},"ratingScale":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["numeric"]},"min":{"type":"number"},"max":{"type":"number"},"step":{"type":"number"},"labels":{"type":"array","items":{"type":"string"}}},"required":["type","min","max","step"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["categorical"]},"values":{"type":"array","items":{"type":"string"}}},"required":["type","values"],"additionalProperties":false}]},"observation":{"type":"object","properties":{"required":{"type":"number"},"minAnnounced":{"type":"number"},"minUnannounced":{"type":"number"},"minTotalMinutes":{"type":"number"}},"additionalProperties":false},"studentGrowth":{"type":"object","properties":{"required":{"type":"boolean"},"weightInFinalScore":{"type":"number"},"label":{"type":"string"},"description":{"type":"string"}},"required":["required","weightInFinalScore","label"],"additionalProperties":false},"scoring":{"type":"object","properties":{"practiceAggregation":{"type":"string","enum":["weighted-average","simple-average","highest"]},"practiceWeight":{"type":"number"},"summativeRatingBands":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"minScore":{"type":"number"},"maxScore":{"type":"number"}},"required":["code","label","minScore","maxScore"],"additionalProperties":false}},"description":{"type":"string"}},"required":["practiceAggregation","practiceWeight","summativeRatingBands"],"additionalProperties":false},"reviewedYear":{"type":"number"}},"required":["code","name","jurisdiction","audience","specRef","href","description","domains","ratingScale","observation","scoring","reviewedYear"],"additionalProperties":false},"source":{"type":"string","enum":["district-override","state-default","fallback-generic"]},"usedFallback":{"type":"boolean"},"requestedCode":{"type":"string","nullable":true},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["framework-unknown-code","framework-not-configured","framework-district-override"]},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}}},"required":["framework","source","usedFallback","requestedCode","warnings"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluation-framework/catalog":{"get":{"summary":"List all built-in evaluation frameworks","tags":["Business Office"],"description":"Returns the full catalog of frameworks Forge ships with. Used by the admin UI to let districts pick an override framework.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"frameworks":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"jurisdiction":{"type":"string","enum":["NJ","CA","TX","NY","FL","IL","PA","multi-state","generic"]},"audience":{"type":"string","enum":["teacher","leader","any"]},"specRef":{"type":"string"},"href":{"type":"string"},"description":{"type":"string"},"domains":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"weight":{"type":"number"},"components":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"required":["code","name"],"additionalProperties":false}}},"required":["code","name"],"additionalProperties":false}},"ratingScale":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["numeric"]},"min":{"type":"number"},"max":{"type":"number"},"step":{"type":"number"},"labels":{"type":"array","items":{"type":"string"}}},"required":["type","min","max","step"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["categorical"]},"values":{"type":"array","items":{"type":"string"}}},"required":["type","values"],"additionalProperties":false}]},"observation":{"type":"object","properties":{"required":{"type":"number"},"minAnnounced":{"type":"number"},"minUnannounced":{"type":"number"},"minTotalMinutes":{"type":"number"}},"additionalProperties":false},"studentGrowth":{"type":"object","properties":{"required":{"type":"boolean"},"weightInFinalScore":{"type":"number"},"label":{"type":"string"},"description":{"type":"string"}},"required":["required","weightInFinalScore","label"],"additionalProperties":false},"scoring":{"type":"object","properties":{"practiceAggregation":{"type":"string","enum":["weighted-average","simple-average","highest"]},"practiceWeight":{"type":"number"},"summativeRatingBands":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"minScore":{"type":"number"},"maxScore":{"type":"number"}},"required":["code","label","minScore","maxScore"],"additionalProperties":false}},"description":{"type":"string"}},"required":["practiceAggregation","practiceWeight","summativeRatingBands"],"additionalProperties":false},"reviewedYear":{"type":"number"}},"required":["code","name","jurisdiction","audience","specRef","href","description","domains","ratingScale","observation","scoring","reviewedYear"],"additionalProperties":false}}},"required":["frameworks"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluations/{id}/detail":{"get":{"summary":"Get full evaluation detail including conferences, artifacts, and observations","tags":["Business Office"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"cycleName":{"type":"string"},"frameworkCode":{"type":"string"},"status":{"type":"string"},"observations":{"type":"array","items":{"type":"object","additionalProperties":{}}},"sgoPlan":{"type":"object","additionalProperties":{},"nullable":true},"finalScore":{"type":"number","nullable":true},"sgoApprovedAt":{"type":"string","format":"date-time","nullable":true},"sgoApprovedByPersonId":{"type":"string","format":"uuid","nullable":true},"conferences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"evaluationId":{"type":"string","format":"uuid"},"conferenceType":{"type":"string","enum":["pre_observation","post_observation","end_of_year"]},"scheduledAt":{"type":"string","format":"date-time"},"heldAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"initiatedByPersonId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","evaluationId","conferenceType","scheduledAt","heldAt","notes","initiatedByPersonId","createdAt","updatedAt"],"additionalProperties":false}},"artifacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"evaluationId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"evidenceUrl":{"type":"string","format":"uri"},"category":{"type":"string","enum":["lesson_plan","assessment","student_work","professional_goal","other"]},"addedByPersonId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","evaluationId","title","description","evidenceUrl","category","addedByPersonId","createdAt","updatedAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","cycleName","frameworkCode","status","observations","sgoPlan","finalScore","sgoApprovedAt","sgoApprovedByPersonId","conferences","artifacts","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluations/mine":{"get":{"summary":"List the signed-in teacher's own evaluation cycles (read-only)","tags":["Business Office"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"cycleName":{"type":"string"},"frameworkCode":{"type":"string"},"status":{"type":"string"},"observations":{"type":"array","items":{"type":"object","additionalProperties":{}}},"sgoPlan":{"type":"object","additionalProperties":{},"nullable":true},"finalScore":{"type":"number","nullable":true},"sgoApprovedAt":{"type":"string","format":"date-time","nullable":true},"sgoApprovedByPersonId":{"type":"string","format":"uuid","nullable":true},"conferences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"evaluationId":{"type":"string","format":"uuid"},"conferenceType":{"type":"string","enum":["pre_observation","post_observation","end_of_year"]},"scheduledAt":{"type":"string","format":"date-time"},"heldAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"initiatedByPersonId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","evaluationId","conferenceType","scheduledAt","heldAt","notes","initiatedByPersonId","createdAt","updatedAt"],"additionalProperties":false}},"artifacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"evaluationId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"evidenceUrl":{"type":"string","format":"uri"},"category":{"type":"string","enum":["lesson_plan","assessment","student_work","professional_goal","other"]},"addedByPersonId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","evaluationId","title","description","evidenceUrl","category","addedByPersonId","createdAt","updatedAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","cycleName","frameworkCode","status","observations","sgoPlan","finalScore","sgoApprovedAt","sgoApprovedByPersonId","conferences","artifacts","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluations/{id}/conferences":{"get":{"summary":"List conferences for an evaluation cycle","tags":["Business Office"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"evaluationId":{"type":"string","format":"uuid"},"conferenceType":{"type":"string","enum":["pre_observation","post_observation","end_of_year"]},"scheduledAt":{"type":"string","format":"date-time"},"heldAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"initiatedByPersonId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","evaluationId","conferenceType","scheduledAt","heldAt","notes","initiatedByPersonId","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Schedule a conference for an evaluation cycle (emits EvalConferenceScheduled)","tags":["Business Office"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"conferenceType":{"type":"string","enum":["pre_observation","post_observation","end_of_year"]},"scheduledAt":{"type":"string","format":"date-time"},"notes":{"type":"string","maxLength":5000}},"required":["conferenceType","scheduledAt"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"evaluationId":{"type":"string","format":"uuid"},"conferenceType":{"type":"string","enum":["pre_observation","post_observation","end_of_year"]},"scheduledAt":{"type":"string","format":"date-time"},"heldAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"initiatedByPersonId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","evaluationId","conferenceType","scheduledAt","heldAt","notes","initiatedByPersonId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluations/{id}/conferences/{subId}":{"patch":{"summary":"Update a conference (mark as held, add notes)","tags":["Business Office"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scheduledAt":{"type":"string","format":"date-time"},"heldAt":{"type":"string","format":"date-time"},"notes":{"type":"string","maxLength":5000}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"subId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"evaluationId":{"type":"string","format":"uuid"},"conferenceType":{"type":"string","enum":["pre_observation","post_observation","end_of_year"]},"scheduledAt":{"type":"string","format":"date-time"},"heldAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"initiatedByPersonId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","evaluationId","conferenceType","scheduledAt","heldAt","notes","initiatedByPersonId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluations/{id}/artifacts":{"get":{"summary":"List evidence artifacts for an evaluation cycle","tags":["Business Office"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"evaluationId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"evidenceUrl":{"type":"string","format":"uri"},"category":{"type":"string","enum":["lesson_plan","assessment","student_work","professional_goal","other"]},"addedByPersonId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","evaluationId","title","description","evidenceUrl","category","addedByPersonId","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Add an evidence artifact (emits EvalArtifactUploaded)","tags":["Business Office"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"evidenceUrl":{"type":"string","format":"uri","maxLength":2000},"category":{"type":"string","enum":["lesson_plan","assessment","student_work","professional_goal","other"]}},"required":["title","evidenceUrl","category"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"evaluationId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"evidenceUrl":{"type":"string","format":"uri"},"category":{"type":"string","enum":["lesson_plan","assessment","student_work","professional_goal","other"]},"addedByPersonId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","evaluationId","title","description","evidenceUrl","category","addedByPersonId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluations/{id}/artifacts/{subId}":{"delete":{"summary":"Soft-delete an evidence artifact","tags":["Business Office"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"subId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluations/{id}/sgo/approve":{"post":{"summary":"Supervisor approves the teacher's SGO plan (emits SgoApproved)","tags":["Business Office"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"cycleName":{"type":"string"},"frameworkCode":{"type":"string"},"status":{"type":"string"},"observations":{"type":"array","items":{"type":"object","additionalProperties":{}}},"sgoPlan":{"type":"object","additionalProperties":{},"nullable":true},"finalScore":{"type":"number","nullable":true},"sgoApprovedAt":{"type":"string","format":"date-time","nullable":true},"sgoApprovedByPersonId":{"type":"string","format":"uuid","nullable":true},"conferences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"evaluationId":{"type":"string","format":"uuid"},"conferenceType":{"type":"string","enum":["pre_observation","post_observation","end_of_year"]},"scheduledAt":{"type":"string","format":"date-time"},"heldAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"initiatedByPersonId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","evaluationId","conferenceType","scheduledAt","heldAt","notes","initiatedByPersonId","createdAt","updatedAt"],"additionalProperties":false}},"artifacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"evaluationId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"evidenceUrl":{"type":"string","format":"uri"},"category":{"type":"string","enum":["lesson_plan","assessment","student_work","professional_goal","other"]},"addedByPersonId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","evaluationId","title","description","evidenceUrl","category","addedByPersonId","createdAt","updatedAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","cycleName","frameworkCode","status","observations","sgoPlan","finalScore","sgoApprovedAt","sgoApprovedByPersonId","conferences","artifacts","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/hr/evaluations/{id}/status":{"patch":{"summary":"Transition an evaluation cycle through the lifecycle","tags":["Business Office"],"description":"Valid transitions: draft → in_progress, in_progress → pending_review, pending_review → complete. The complete route (POST /complete) closes the cycle with a computed score — use this route only to transition back to pending_review if a score needs revision, or draft → in_progress.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["draft","in_progress","pending_review","complete"]}},"required":["status"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["draft","in_progress","pending_review","complete"]},"previousStatus":{"type":"string"}},"required":["id","status","previousStatus"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/ai/report-card-comment":{"post":{"summary":"Draft a grounded report-card comment for one (student, section, term)","tags":["AI"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"sectionId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"}},"required":["studentId","sectionId","termId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"content":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false}},"promptId":{"type":"string"}},"required":["content","citations","promptId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/ai/student-summary":{"post":{"summary":"Generate a grounded summary for one student","tags":["AI"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"}},"required":["studentId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"content":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false}},"promptId":{"type":"string"}},"required":["content","citations","promptId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/ai/ask":{"post":{"summary":"Parent portal Q&A — grounded in the asking guardian’s visible data","tags":["AI"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"question":{"type":"string","minLength":5,"maxLength":1000}},"required":["studentId","question"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"content":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false}},"promptId":{"type":"string"}},"required":["content","citations","promptId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/ai/early-warning":{"post":{"summary":"Grounded early-warning narrative for one student","tags":["AI"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"}},"required":["studentId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"content":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false}},"promptId":{"type":"string"}},"required":["content","citations","promptId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/ai/teacher-copilot":{"post":{"summary":"Weekly digest for one section (trends + check-ins + overdue)","tags":["AI"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sectionId":{"type":"string","format":"uuid"}},"required":["sectionId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"content":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false}},"promptId":{"type":"string"}},"required":["content","citations","promptId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/ai/nlq":{"post":{"summary":"Turn a natural-language question into a read-only query plan","tags":["AI"],"description":"Returns a JSON plan (no execution). The admin console previews the plan before running it; SQL injection is impossible because the API validates the plan against an allowlist of tables + filter keys.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","minLength":5,"maxLength":1000}},"required":["question"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"content":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false}},"promptId":{"type":"string"}},"required":["content","citations","promptId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/ai/usage":{"get":{"summary":"AI usage and cost for this district (last 1000 calls)","tags":["AI"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"totalCalls":{"type":"integer"},"totalCostUsd":{"type":"number"},"byPromptId":{"type":"array","items":{"type":"object","properties":{"promptId":{"type":"string"},"calls":{"type":"integer"},"costUsd":{"type":"number"}},"required":["promptId","calls","costUsd"],"additionalProperties":false}},"recent":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"promptId":{"type":"string"},"provider":{"type":"string"},"model":{"type":"string"},"costUsd":{"type":"number"},"latencyMs":{"type":"integer"},"occurredAt":{"type":"string","format":"date-time"}},"required":["id","promptId","provider","model","costUsd","latencyMs","occurredAt"],"additionalProperties":false}}},"required":["totalCalls","totalCostUsd","byPromptId","recent"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/ai/registration/documents/extract":{"post":{"summary":"Extract structured fields from a scanned registration document","tags":["AI"],"description":"Vision endpoint — takes a base64 image or PDF and returns a typed field bag plus region citations. Registrars click \"Extract\" to pre-fill the application from uploaded documents; the human always reviews before saving.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["birth-certificate","residency-proof","immunization","transcript","iep","other"]},"mediaType":{"type":"string","enum":["image/jpeg","image/png","image/webp","image/gif","application/pdf"]},"base64":{"type":"string","minLength":100,"maxLength":25000000},"schema":{"type":"object","additionalProperties":{}}},"required":["kind","mediaType","base64"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{}},"citations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false}},"promptId":{"type":"string"}},"required":["fields","citations","promptId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/ai/translate":{"post":{"summary":"Translate a short school message into a target language","tags":["AI"],"description":"Used by the messaging composer to reach families in their home language. Preserves proper nouns, dates, and times. Non-grounded prompt — the source text is the only authoritative input.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":20000},"targetLanguage":{"type":"string","minLength":2,"maxLength":40},"sourceLanguage":{"type":"string","minLength":2,"maxLength":40},"audience":{"type":"string","enum":["parent","student","staff"],"default":"parent"}},"required":["text","targetLanguage"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"translatedText":{"type":"string"},"targetLanguage":{"type":"string"},"promptId":{"type":"string"}},"required":["translatedText","targetLanguage","promptId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/ai/nurse/visit-note/expand":{"post":{"summary":"Expand a nurse’s shorthand into a SOAP-structured visit note","tags":["AI"],"description":"Optional `studentId` pulls the student’s last 3 visits as grounding so the narrative is consistent with prior care.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"shorthand":{"type":"string","minLength":1,"maxLength":2000},"studentId":{"type":"string","format":"uuid"}},"required":["shorthand"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"content":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false}},"promptId":{"type":"string"}},"required":["content","citations","promptId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/ai/iep/progress-narrative":{"post":{"summary":"Draft a quarterly IEP-goal progress narrative for one student","tags":["AI"],"description":"Pulls recent assignment scores + attendance + any assertions on the student record and drafts a parent-facing narrative. Teacher of record reviews before saving into the IEP.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"goalText":{"type":"string","minLength":1,"maxLength":1000},"quarter":{"type":"string","minLength":1,"maxLength":20}},"required":["studentId","goalText","quarter"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"content":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false}},"promptId":{"type":"string"}},"required":["content","citations","promptId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/ai/scheduling/propose-change":{"post":{"summary":"Parse a free-text schedule-change request into structured operations","tags":["AI"],"description":"Preview-only — returns the operations the scheduler would need to execute. No changes are applied until the admin confirms via the existing scheduling endpoints.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request":{"type":"string","minLength":3,"maxLength":2000}},"required":["request"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"operations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"args":{"type":"object","additionalProperties":{}}},"required":["type","args"],"additionalProperties":false}},"summary":{"type":"string"},"promptId":{"type":"string"}},"required":["operations","summary","promptId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/ai/grading/rubric-score":{"post":{"summary":"Draft rubric-aligned scores and a teacher comment for a student essay","tags":["AI"],"description":"The teacher retains final authority — this endpoint produces a draft score with evidence quoted verbatim from the essay and a suggested comment. Every `evidence` value must be a substring of the essay.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"essay":{"type":"string","minLength":20,"maxLength":40000},"rubric":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"criteria":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":1000},"maxScore":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":100},"levels":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string"},"description":{"type":"string"},"points":{"type":"number"}},"required":["level","description","points"],"additionalProperties":false}}},"required":["name","maxScore"],"additionalProperties":false},"minItems":1,"maxItems":12}},"required":["criteria"],"additionalProperties":false},"studentLabel":{"type":"string","maxLength":100}},"required":["essay","rubric"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"overallScore":{"type":"number"},"maxScore":{"type":"number"},"criteria":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"score":{"type":"number"},"maxScore":{"type":"number"},"rationale":{"type":"string"},"evidence":{"type":"string"}},"required":["name","score","maxScore","rationale","evidence"],"additionalProperties":false}},"suggestedComment":{"type":"string"},"promptId":{"type":"string"}},"required":["overallScore","maxScore","criteria","suggestedComment","promptId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/dashboard/teacher/me":{"get":{"summary":"Summary for the signed-in teacher’s dashboard","tags":["Dashboard"],"description":"Resolves the teacher’s Person row from the session, lists their current sections, and computes per-section attendance + grade averages plus a 10-day attendance/grade sparkline from real rows.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"teacher":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"}},"required":["id","firstName","lastName"],"additionalProperties":false},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"sectionCode":{"type":"string"},"rosterSize":{"type":"integer"},"attendanceRatePct":{"type":"number","nullable":true},"averageGradePct":{"type":"number","nullable":true}},"required":["id","name","sectionCode","rosterSize","attendanceRatePct","averageGradePct"],"additionalProperties":false}},"stats":{"type":"object","properties":{"sectionCount":{"type":"integer"},"rosterTotal":{"type":"integer"},"attendanceTodayPct":{"type":"number","nullable":true},"attendanceTrendPct":{"type":"array","items":{"type":"number"}},"classAveragePct":{"type":"number","nullable":true},"classAverageTrendPct":{"type":"array","items":{"type":"number"}},"assignmentsToGrade":{"type":"integer"}},"required":["sectionCount","rosterTotal","attendanceTodayPct","attendanceTrendPct","classAveragePct","classAverageTrendPct","assignmentsToGrade"],"additionalProperties":false}},"required":["teacher","sections","stats"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/dashboard/admin/summary":{"get":{"summary":"District-wide rollups for the admin overview","tags":["Dashboard"],"description":"Enrollment count + trend, attendance rate + trend, open compliance findings, open incidents, pending registration applications, health visits in the past 7 days, and AI cost for the last 30 days.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"stats":{"type":"object","properties":{"enrollment":{"type":"integer"},"enrollmentTrend":{"type":"array","items":{"type":"integer"},"nullable":true},"attendanceRatePct":{"type":"number","nullable":true},"attendanceTrendPct":{"type":"array","items":{"type":"number"}},"openComplianceFindings":{"type":"integer"},"complianceScorePct":{"type":"number","nullable":true},"complianceTrendPct":{"type":"array","items":{"type":"number"},"nullable":true},"openIncidents":{"type":"integer"},"pendingRegistrations":{"type":"integer"},"healthVisitsPast7Days":{"type":"integer"}},"required":["enrollment","enrollmentTrend","attendanceRatePct","attendanceTrendPct","openComplianceFindings","complianceScorePct","complianceTrendPct","openIncidents","pendingRegistrations","healthVisitsPast7Days"],"additionalProperties":false},"staff":{"type":"object","properties":{"total":{"type":"integer"}},"required":["total"],"additionalProperties":false},"ai":{"type":"object","properties":{"callsPast30Days":{"type":"integer"},"costUsdPast30Days":{"type":"number"}},"required":["callsPast30Days","costUsdPast30Days"],"additionalProperties":false}},"required":["stats","staff","ai"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/dashboard/superintendent":{"get":{"summary":"Executive overview for the district superintendent","tags":["Dashboard"],"description":"Aggregates student metrics, compliance alerts, staff KPIs, financial snapshot, recent event activity, and state reporting deadlines into a single payload for the superintendent dashboard.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"students":{"type":"object","properties":{"totalEnrolled":{"type":"integer"},"attendanceRateToday":{"type":"number","nullable":true},"adaForTerm":{"type":"number","nullable":true},"activeIepCount":{"type":"integer"}},"required":["totalEnrolled","attendanceRateToday","adaForTerm","activeIepCount"],"additionalProperties":false},"compliance":{"type":"object","properties":{"topFindings":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"severity":{"type":"string","enum":["blocker","warn","info"]},"message":{"type":"string"},"subjectType":{"type":"string"},"count":{"type":"integer"}},"required":["ruleId","severity","message","subjectType","count"],"additionalProperties":false}}},"required":["topFindings"],"additionalProperties":false},"staff":{"type":"object","properties":{"totalActive":{"type":"integer"},"openSubJobsToday":{"type":"integer"},"evaluationsPendingThisMonth":{"type":"integer"}},"required":["totalActive","openSubJobsToday","evaluationsPendingThisMonth"],"additionalProperties":false},"financial":{"type":"object","properties":{"feesOutstandingCents":{"type":"integer"},"poCommittedCents":{"type":"integer"},"poBudgetCents":{"type":"integer"}},"required":["feesOutstandingCents","poCommittedCents","poBudgetCents"],"additionalProperties":false},"recentActivity":{"type":"array","items":{"type":"object","properties":{"eventType":{"type":"string"},"actorId":{"type":"string","format":"uuid","nullable":true},"subjectType":{"type":"string","nullable":true},"occurredAt":{"type":"string","format":"date-time"}},"required":["eventType","actorId","subjectType","occurredAt"],"additionalProperties":false}},"stateReportDeadlines":{"type":"array","items":{"type":"object","properties":{"reportType":{"type":"string"},"dueDate":{"type":"string","format":"date"},"daysRemaining":{"type":"integer"}},"required":["reportType","dueDate","daysRemaining"],"additionalProperties":false}}},"required":["students","compliance","staff","financial","recentActivity","stateReportDeadlines"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/registration/districts/{districtId}/applications":{"post":{"summary":"Submit a new family / re-registration application","tags":["Registration"],"description":"Public endpoint used by the registration wizard. Returns an access token families use to resume the draft and upload documents.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["new-family","re-registration","transfer"]},"targetSchoolYearId":{"type":"string","format":"uuid"},"targetOrganizationId":{"type":"string","format":"uuid"},"targetGrade":{"type":"string","maxLength":10},"studentFirstName":{"type":"string","minLength":1,"maxLength":100},"studentLastName":{"type":"string","minLength":1,"maxLength":100},"studentMiddleName":{"type":"string","maxLength":100},"studentDob":{"type":"string","format":"date"},"studentGender":{"type":"string","maxLength":20},"studentEmail":{"type":"string","format":"email"},"studentPhone":{"type":"string","maxLength":30},"guardians":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"relationshipType":{"type":"string","minLength":1,"maxLength":30},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":30},"emergencyPriority":{"type":"integer","minimum":1,"maximum":99},"hasCustody":{"type":"boolean"}},"required":["firstName","lastName","relationshipType"],"additionalProperties":false},"minItems":1},"residency":{"type":"object","properties":{"addressLine1":{"type":"string","minLength":1,"maxLength":200},"addressLine2":{"type":"string","maxLength":200},"city":{"type":"string","minLength":1,"maxLength":100},"state":{"type":"string","minLength":2,"maxLength":2},"zipCode":{"type":"string","minLength":5,"maxLength":10},"proofType":{"type":"string","maxLength":50}},"required":["addressLine1","city","state","zipCode"],"additionalProperties":false},"health":{"type":"object","additionalProperties":{}},"prevSchool":{"type":"object","additionalProperties":{}}},"required":["type","studentFirstName","studentLastName","guardians","residency"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accessToken":{"type":"string"},"status":{"type":"string"}},"required":["id","accessToken","status"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/registration/districts/{districtId}/applications/by-token/{token}":{"get":{"summary":"Resume a registration draft by access token","tags":["Registration"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true},{"schema":{"type":"string","minLength":8,"maxLength":128},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"type":{"type":"string"},"studentFirstName":{"type":"string"},"studentLastName":{"type":"string"},"targetGrade":{"type":"string","nullable":true},"submittedAt":{"type":"string","format":"date-time","nullable":true},"reviewedAt":{"type":"string","format":"date-time","nullable":true},"createdPersonId":{"type":"string","format":"uuid","nullable":true},"studentMiddleName":{"type":"string","nullable":true},"studentDob":{"type":"string","format":"date","nullable":true},"studentGender":{"type":"string","nullable":true},"studentEmail":{"type":"string","format":"email","nullable":true},"studentPhone":{"type":"string","nullable":true},"guardians":{"type":"array","items":{"type":"object","additionalProperties":{}}},"residency":{"type":"object","additionalProperties":{}},"health":{"type":"object","additionalProperties":{},"nullable":true},"prevSchool":{"type":"object","additionalProperties":{},"nullable":true},"rejectionReason":{"type":"string","nullable":true},"reviewNotes":{"type":"string","nullable":true},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string"},"filename":{"type":"string"},"contentType":{"type":"string"},"sizeBytes":{"type":"integer"},"verifiedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","kind","filename","contentType","sizeBytes","verifiedAt","createdAt"],"additionalProperties":false}}},"required":["id","status","type","studentFirstName","studentLastName","targetGrade","submittedAt","reviewedAt","createdPersonId","studentMiddleName","studentDob","studentGender","studentEmail","studentPhone","guardians","residency","health","prevSchool","rejectionReason","reviewNotes","documents"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/registration/districts/{districtId}/applications/by-token/{token}/documents":{"post":{"summary":"Attach an uploaded document to an application","tags":["Registration"],"description":"The actual bytes are uploaded to object storage out-of-band; this records the metadata + storage key.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["birth-certificate","residency-proof","immunization","transcript","iep","other"]},"filename":{"type":"string","minLength":1,"maxLength":300},"contentType":{"type":"string","minLength":1,"maxLength":100},"sizeBytes":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":52428800},"storageKey":{"type":"string","minLength":1,"maxLength":500},"checksumSha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"required":["kind","filename","contentType","sizeBytes","storageKey","checksumSha256"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true},{"schema":{"type":"string","minLength":8,"maxLength":128},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"}},"required":["id","applicationId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/registration/applications":{"get":{"summary":"List registration applications (registrar view)","tags":["Registration"],"parameters":[{"schema":{"type":"string","enum":["draft","submitted","under-review","approved","rejected","withdrawn"]},"in":"query","name":"status","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"type":{"type":"string"},"studentFirstName":{"type":"string"},"studentLastName":{"type":"string"},"targetGrade":{"type":"string","nullable":true},"submittedAt":{"type":"string","format":"date-time","nullable":true},"reviewedAt":{"type":"string","format":"date-time","nullable":true},"createdPersonId":{"type":"string","format":"uuid","nullable":true}},"required":["id","status","type","studentFirstName","studentLastName","targetGrade","submittedAt","reviewedAt","createdPersonId"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}}}}},"/registration/applications/{id}":{"get":{"summary":"Get a full application (registrar view)","tags":["Registration"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"type":{"type":"string"},"studentFirstName":{"type":"string"},"studentLastName":{"type":"string"},"targetGrade":{"type":"string","nullable":true},"submittedAt":{"type":"string","format":"date-time","nullable":true},"reviewedAt":{"type":"string","format":"date-time","nullable":true},"createdPersonId":{"type":"string","format":"uuid","nullable":true},"studentMiddleName":{"type":"string","nullable":true},"studentDob":{"type":"string","format":"date","nullable":true},"studentGender":{"type":"string","nullable":true},"studentEmail":{"type":"string","format":"email","nullable":true},"studentPhone":{"type":"string","nullable":true},"guardians":{"type":"array","items":{"type":"object","additionalProperties":{}}},"residency":{"type":"object","additionalProperties":{}},"health":{"type":"object","additionalProperties":{},"nullable":true},"prevSchool":{"type":"object","additionalProperties":{},"nullable":true},"rejectionReason":{"type":"string","nullable":true},"reviewNotes":{"type":"string","nullable":true},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string"},"filename":{"type":"string"},"contentType":{"type":"string"},"sizeBytes":{"type":"integer"},"verifiedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","kind","filename","contentType","sizeBytes","verifiedAt","createdAt"],"additionalProperties":false}}},"required":["id","status","type","studentFirstName","studentLastName","targetGrade","submittedAt","reviewedAt","createdPersonId","studentMiddleName","studentDob","studentGender","studentEmail","studentPhone","guardians","residency","health","prevSchool","rejectionReason","reviewNotes","documents"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/registration/applications/{id}/approve":{"post":{"summary":"Approve an application and create the student + enrollment","tags":["Registration"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","maxLength":2000}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"enrollmentId":{"type":"string","format":"uuid","nullable":true}},"required":["personId","enrollmentId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/registration/applications/{id}/reject":{"post":{"summary":"Reject an application","tags":["Registration"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":2000}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/reports/catalog":{"get":{"summary":"List the field catalog for every report scope","tags":["Reports"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"scope":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"pii":{"type":"boolean"}},"required":["id","label","type"],"additionalProperties":false}}},"required":["scope","fields"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/reports/custom":{"get":{"summary":"List saved custom reports","tags":["Reports"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"scope","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"scope":{"type":"string"},"isShared":{"type":"boolean"},"allowedRoles":{"type":"array","items":{"type":"string"}},"createdBy":{"type":"string","format":"uuid","nullable":true},"schedule":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","scope","isShared","allowedRoles","createdBy","schedule","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a saved custom report","tags":["Reports"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"definition":{"type":"object","properties":{"scope":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":30},"filters":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["eq","neq","in","notIn","gt","gte","lt","lte","contains","startsWith","isNull","notNull"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]}},"required":["field","op"],"additionalProperties":false},"default":[]},"sort":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"],"default":"asc"}},"required":["field"],"additionalProperties":false},"default":[]},"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":10000,"default":1000}},"required":["scope","fields"],"additionalProperties":false},"allowedRoles":{"type":"array","items":{"type":"string"},"default":["district_admin"]},"isShared":{"type":"boolean","default":false},"schedule":{"type":"string","maxLength":100}},"required":["name","definition"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"scope":{"type":"string"},"isShared":{"type":"boolean"},"allowedRoles":{"type":"array","items":{"type":"string"}},"createdBy":{"type":"string","format":"uuid","nullable":true},"schedule":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"definition":{"type":"object","properties":{"scope":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":30},"filters":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["eq","neq","in","notIn","gt","gte","lt","lte","contains","startsWith","isNull","notNull"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]}},"required":["field","op"],"additionalProperties":false},"default":[]},"sort":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"],"default":"asc"}},"required":["field"],"additionalProperties":false},"default":[]},"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":10000,"default":1000}},"required":["scope","fields"],"additionalProperties":false}},"required":["id","name","description","scope","isShared","allowedRoles","createdBy","schedule","createdAt","updatedAt","definition"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/reports/custom/{id}":{"get":{"summary":"Get a saved custom report","tags":["Reports"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"scope":{"type":"string"},"isShared":{"type":"boolean"},"allowedRoles":{"type":"array","items":{"type":"string"}},"createdBy":{"type":"string","format":"uuid","nullable":true},"schedule":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"definition":{"type":"object","properties":{"scope":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":30},"filters":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["eq","neq","in","notIn","gt","gte","lt","lte","contains","startsWith","isNull","notNull"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]}},"required":["field","op"],"additionalProperties":false},"default":[]},"sort":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"],"default":"asc"}},"required":["field"],"additionalProperties":false},"default":[]},"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":10000,"default":1000}},"required":["scope","fields"],"additionalProperties":false}},"required":["id","name","description","scope","isShared","allowedRoles","createdBy","schedule","createdAt","updatedAt","definition"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"put":{"summary":"Update a saved custom report","tags":["Reports"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"definition":{"type":"object","properties":{"scope":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":30},"filters":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["eq","neq","in","notIn","gt","gte","lt","lte","contains","startsWith","isNull","notNull"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]}},"required":["field","op"],"additionalProperties":false},"default":[]},"sort":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"],"default":"asc"}},"required":["field"],"additionalProperties":false},"default":[]},"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":10000,"default":1000}},"required":["scope","fields"],"additionalProperties":false},"allowedRoles":{"type":"array","items":{"type":"string"},"default":["district_admin"]},"isShared":{"type":"boolean","default":false},"schedule":{"type":"string","maxLength":100}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"scope":{"type":"string"},"isShared":{"type":"boolean"},"allowedRoles":{"type":"array","items":{"type":"string"}},"createdBy":{"type":"string","format":"uuid","nullable":true},"schedule":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"definition":{"type":"object","properties":{"scope":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":30},"filters":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["eq","neq","in","notIn","gt","gte","lt","lte","contains","startsWith","isNull","notNull"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]}},"required":["field","op"],"additionalProperties":false},"default":[]},"sort":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"],"default":"asc"}},"required":["field"],"additionalProperties":false},"default":[]},"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":10000,"default":1000}},"required":["scope","fields"],"additionalProperties":false}},"required":["id","name","description","scope","isShared","allowedRoles","createdBy","schedule","createdAt","updatedAt","definition"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a saved custom report","tags":["Reports"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/reports/custom/{id}/run":{"post":{"summary":"Execute a saved report and return the result set","tags":["Reports"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"params":{"type":"object","additionalProperties":{}},"allowPii":{"type":"boolean","default":false}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"type":"string","format":"uuid"},"durationMs":{"type":"integer"},"columns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"}},"required":["id","label","type"],"additionalProperties":false}},"rows":{"type":"array","items":{"type":"object","additionalProperties":{}}},"rowCount":{"type":"integer"},"truncated":{"type":"boolean"}},"required":["runId","durationMs","columns","rows","rowCount","truncated"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/reports/custom/{id}/export":{"get":{"summary":"Export a saved report as CSV","tags":["Reports"],"parameters":[{"schema":{"type":"boolean","default":false},"in":"query","name":"allowPii","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/lookups/categories":{"get":{"summary":"List every lookup category available to this caller","tags":["Lookups"],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Z]{2}$"},"in":"query","name":"state","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/lookups/{category}":{"get":{"summary":"Get the active options for a lookup category","tags":["Lookups"],"description":"Merges platform defaults → state defaults → district overrides. Sorted by sortOrder then label.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Z]{2}$"},"in":"query","name":"state","required":false},{"schema":{"type":"string","minLength":1,"maxLength":60,"pattern":"^[a-z][a-z0-9_]*$"},"in":"path","name":"category","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"category":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"sortOrder":{"type":"integer"},"metadata":{"type":"object","additionalProperties":{},"nullable":true},"scope":{"type":"string","enum":["platform","state","district"]}},"required":["code","label","description","sortOrder","metadata","scope"],"additionalProperties":false}}},"required":["category","options"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/students/{id}/transcript":{"get":{"summary":"Get a student’s transcript (registrar view)","tags":["Transcripts"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","smid"],"additionalProperties":false},"summary":{"type":"object","properties":{"cumulativeGpa":{"type":"number","nullable":true},"cumulativeGpaWeighted":{"type":"number","nullable":true},"creditsEarned":{"type":"number"},"creditsNeeded":{"type":"number"},"classRank":{"type":"integer","nullable":true},"classRankSize":{"type":"integer","nullable":true},"honorRollLevel":{"type":"string","nullable":true}},"required":["cumulativeGpa","cumulativeGpaWeighted","creditsEarned","creditsNeeded","classRank","classRankSize","honorRollLevel"],"additionalProperties":false},"years":{"type":"array","items":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"schoolYearName":{"type":"string"},"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"schoolYearName":{"type":"string"},"schoolName":{"type":"string"},"gradeLevel":{"type":"string"},"termLabel":{"type":"string"},"courseCode":{"type":"string"},"courseName":{"type":"string"},"subjectArea":{"type":"string"},"finalPercent":{"type":"number","nullable":true},"finalLetter":{"type":"string","nullable":true},"creditsAttempted":{"type":"number"},"creditsEarned":{"type":"number"},"gpaPoints":{"type":"number"},"gpaPointsWeighted":{"type":"number","nullable":true},"isHonors":{"type":"boolean"},"isAP":{"type":"boolean"},"isDualEnrollment":{"type":"boolean"},"source":{"type":"string"},"transferInDistrict":{"type":"string","nullable":true}},"required":["id","schoolYearId","schoolYearName","schoolName","gradeLevel","termLabel","courseCode","courseName","subjectArea","finalPercent","finalLetter","creditsAttempted","creditsEarned","gpaPoints","gpaPointsWeighted","isHonors","isAP","isDualEnrollment","source","transferInDistrict"],"additionalProperties":false}},"yearGpaUnweighted":{"type":"number","nullable":true},"yearGpaWeighted":{"type":"number","nullable":true},"yearCreditsEarned":{"type":"number"}},"required":["schoolYearId","schoolYearName","rows","yearGpaUnweighted","yearGpaWeighted","yearCreditsEarned"],"additionalProperties":false}}},"required":["student","summary","years"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/students/{id}/transcript.pdf":{"get":{"summary":"Download a student’s transcript as a PDF","tags":["Transcripts"],"description":"Renders an official-style transcript PDF using pdf-lib. Single binary response with content-type application/pdf.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/student/me/transcript":{"get":{"summary":"Current student’s own transcript","tags":["Transcripts"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","smid"],"additionalProperties":false},"summary":{"type":"object","properties":{"cumulativeGpa":{"type":"number","nullable":true},"cumulativeGpaWeighted":{"type":"number","nullable":true},"creditsEarned":{"type":"number"},"creditsNeeded":{"type":"number"},"classRank":{"type":"integer","nullable":true},"classRankSize":{"type":"integer","nullable":true},"honorRollLevel":{"type":"string","nullable":true}},"required":["cumulativeGpa","cumulativeGpaWeighted","creditsEarned","creditsNeeded","classRank","classRankSize","honorRollLevel"],"additionalProperties":false},"years":{"type":"array","items":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"schoolYearName":{"type":"string"},"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"schoolYearName":{"type":"string"},"schoolName":{"type":"string"},"gradeLevel":{"type":"string"},"termLabel":{"type":"string"},"courseCode":{"type":"string"},"courseName":{"type":"string"},"subjectArea":{"type":"string"},"finalPercent":{"type":"number","nullable":true},"finalLetter":{"type":"string","nullable":true},"creditsAttempted":{"type":"number"},"creditsEarned":{"type":"number"},"gpaPoints":{"type":"number"},"gpaPointsWeighted":{"type":"number","nullable":true},"isHonors":{"type":"boolean"},"isAP":{"type":"boolean"},"isDualEnrollment":{"type":"boolean"},"source":{"type":"string"},"transferInDistrict":{"type":"string","nullable":true}},"required":["id","schoolYearId","schoolYearName","schoolName","gradeLevel","termLabel","courseCode","courseName","subjectArea","finalPercent","finalLetter","creditsAttempted","creditsEarned","gpaPoints","gpaPointsWeighted","isHonors","isAP","isDualEnrollment","source","transferInDistrict"],"additionalProperties":false}},"yearGpaUnweighted":{"type":"number","nullable":true},"yearGpaWeighted":{"type":"number","nullable":true},"yearCreditsEarned":{"type":"number"}},"required":["schoolYearId","schoolYearName","rows","yearGpaUnweighted","yearGpaWeighted","yearCreditsEarned"],"additionalProperties":false}}},"required":["student","summary","years"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/honor-roll":{"get":{"summary":"District honor roll (current term, by cumulative GPA)","tags":["Transcripts"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"cumulativeGpa":{"type":"number","nullable":true},"honorRollLevel":{"type":"string","nullable":true},"classRank":{"type":"integer","nullable":true},"classRankSize":{"type":"integer","nullable":true}},"required":["studentPersonId","firstName","lastName","gradeLevel","cumulativeGpa","honorRollLevel","classRank","classRankSize"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/transcripts/backfill":{"post":{"summary":"Backfill academic records from SectionGrade for a school year","tags":["Transcripts"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"allYears":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"studentsProcessed":{"type":"integer"},"recordsUpserted":{"type":"integer"}},"required":["studentsProcessed","recordsUpserted"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/transcripts/refresh-metrics":{"post":{"summary":"Recompute GPA / credits / class rank / honor roll for a cohort","tags":["Transcripts"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":5000}},"required":["studentIds"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"studentsProcessed":{"type":"integer"}},"required":["studentsProcessed"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/report-cards/generate":{"post":{"summary":"Generate / refresh report cards for every student in a term","tags":["Report cards"],"description":"Idempotent: re-running refreshes snapshots but preserves ‘published’ status.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"termId":{"type":"string","format":"uuid"}},"required":["termId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"termId":{"type":"string","format":"uuid"},"studentsProcessed":{"type":"integer"},"reportCardsUpserted":{"type":"integer"}},"required":["termId","studentsProcessed","reportCardsUpserted"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/report-cards/lock":{"post":{"summary":"Lock (freeze) all draft report cards in a term","tags":["Report cards"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"termId":{"type":"string","format":"uuid"}},"required":["termId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"locked":{"type":"integer"}},"required":["locked"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/report-cards/publish":{"post":{"summary":"Publish report cards to families (marks them as visible)","tags":["Report cards"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"termId":{"type":"string","format":"uuid"}},"required":["termId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"published":{"type":"integer"}},"required":["published"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/report-cards":{"get":{"summary":"List report cards for a term (registrar view)","tags":["Report cards"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"termId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"status":{"type":"string"},"lockedAt":{"type":"string","format":"date-time","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"generatedByUserId":{"type":"string","format":"uuid","nullable":true},"snapshot":{"type":"object","properties":{"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"schoolName":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","schoolName","smid"],"additionalProperties":false},"term":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"schoolYearName":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"}},"required":["id","name","schoolYearName","startDate","endDate"],"additionalProperties":false},"courses":{"type":"array","items":{"type":"object","properties":{"sectionId":{"type":"string","format":"uuid"},"sectionCode":{"type":"string"},"courseCode":{"type":"string"},"courseName":{"type":"string"},"teacherName":{"type":"string","nullable":true},"percentGrade":{"type":"number","nullable":true},"letterGrade":{"type":"string","nullable":true},"gpaValue":{"type":"number","nullable":true},"missingAssignments":{"type":"integer"},"categoryBreakdown":{"type":"object","additionalProperties":{}},"comment":{"type":"string","nullable":true},"commentSource":{"type":"string","nullable":true}},"required":["sectionId","sectionCode","courseCode","courseName","teacherName","percentGrade","letterGrade","gpaValue","missingAssignments","categoryBreakdown","comment","commentSource"],"additionalProperties":false}},"attendance":{"type":"object","properties":{"present":{"type":"integer"},"absent":{"type":"integer"},"tardy":{"type":"integer"},"excused":{"type":"integer"},"total":{"type":"integer"},"rate":{"type":"number","nullable":true}},"required":["present","absent","tardy","excused","total","rate"],"additionalProperties":false},"summary":{"type":"object","properties":{"termGpa":{"type":"number","nullable":true},"termGpaWeighted":{"type":"number","nullable":true},"creditsAttempted":{"type":"number"},"totalMissing":{"type":"integer"},"coursesCount":{"type":"integer"}},"required":["termGpa","termGpaWeighted","creditsAttempted","totalMissing","coursesCount"],"additionalProperties":false}},"required":["student","term","courses","attendance","summary"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","termId","status","lockedAt","publishedAt","generatedByUserId","snapshot","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/students/{id}/report-cards":{"get":{"summary":"All report cards for a specific student","tags":["Report cards"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"status":{"type":"string"},"lockedAt":{"type":"string","format":"date-time","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"generatedByUserId":{"type":"string","format":"uuid","nullable":true},"snapshot":{"type":"object","properties":{"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"schoolName":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","schoolName","smid"],"additionalProperties":false},"term":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"schoolYearName":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"}},"required":["id","name","schoolYearName","startDate","endDate"],"additionalProperties":false},"courses":{"type":"array","items":{"type":"object","properties":{"sectionId":{"type":"string","format":"uuid"},"sectionCode":{"type":"string"},"courseCode":{"type":"string"},"courseName":{"type":"string"},"teacherName":{"type":"string","nullable":true},"percentGrade":{"type":"number","nullable":true},"letterGrade":{"type":"string","nullable":true},"gpaValue":{"type":"number","nullable":true},"missingAssignments":{"type":"integer"},"categoryBreakdown":{"type":"object","additionalProperties":{}},"comment":{"type":"string","nullable":true},"commentSource":{"type":"string","nullable":true}},"required":["sectionId","sectionCode","courseCode","courseName","teacherName","percentGrade","letterGrade","gpaValue","missingAssignments","categoryBreakdown","comment","commentSource"],"additionalProperties":false}},"attendance":{"type":"object","properties":{"present":{"type":"integer"},"absent":{"type":"integer"},"tardy":{"type":"integer"},"excused":{"type":"integer"},"total":{"type":"integer"},"rate":{"type":"number","nullable":true}},"required":["present","absent","tardy","excused","total","rate"],"additionalProperties":false},"summary":{"type":"object","properties":{"termGpa":{"type":"number","nullable":true},"termGpaWeighted":{"type":"number","nullable":true},"creditsAttempted":{"type":"number"},"totalMissing":{"type":"integer"},"coursesCount":{"type":"integer"}},"required":["termGpa","termGpaWeighted","creditsAttempted","totalMissing","coursesCount"],"additionalProperties":false}},"required":["student","term","courses","attendance","summary"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","termId","status","lockedAt","publishedAt","generatedByUserId","snapshot","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/students/{id}/report-cards/{termId}":{"get":{"summary":"Get a single report card for a student + term","tags":["Report cards"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"termId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"status":{"type":"string"},"lockedAt":{"type":"string","format":"date-time","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"generatedByUserId":{"type":"string","format":"uuid","nullable":true},"snapshot":{"type":"object","properties":{"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"schoolName":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","schoolName","smid"],"additionalProperties":false},"term":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"schoolYearName":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"}},"required":["id","name","schoolYearName","startDate","endDate"],"additionalProperties":false},"courses":{"type":"array","items":{"type":"object","properties":{"sectionId":{"type":"string","format":"uuid"},"sectionCode":{"type":"string"},"courseCode":{"type":"string"},"courseName":{"type":"string"},"teacherName":{"type":"string","nullable":true},"percentGrade":{"type":"number","nullable":true},"letterGrade":{"type":"string","nullable":true},"gpaValue":{"type":"number","nullable":true},"missingAssignments":{"type":"integer"},"categoryBreakdown":{"type":"object","additionalProperties":{}},"comment":{"type":"string","nullable":true},"commentSource":{"type":"string","nullable":true}},"required":["sectionId","sectionCode","courseCode","courseName","teacherName","percentGrade","letterGrade","gpaValue","missingAssignments","categoryBreakdown","comment","commentSource"],"additionalProperties":false}},"attendance":{"type":"object","properties":{"present":{"type":"integer"},"absent":{"type":"integer"},"tardy":{"type":"integer"},"excused":{"type":"integer"},"total":{"type":"integer"},"rate":{"type":"number","nullable":true}},"required":["present","absent","tardy","excused","total","rate"],"additionalProperties":false},"summary":{"type":"object","properties":{"termGpa":{"type":"number","nullable":true},"termGpaWeighted":{"type":"number","nullable":true},"creditsAttempted":{"type":"number"},"totalMissing":{"type":"integer"},"coursesCount":{"type":"integer"}},"required":["termGpa","termGpaWeighted","creditsAttempted","totalMissing","coursesCount"],"additionalProperties":false}},"required":["student","term","courses","attendance","summary"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","termId","status","lockedAt","publishedAt","generatedByUserId","snapshot","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/student/me/report-cards":{"get":{"summary":"Current student’s published report cards","tags":["Report cards"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"termId":{"type":"string","format":"uuid"},"status":{"type":"string"},"lockedAt":{"type":"string","format":"date-time","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"generatedByUserId":{"type":"string","format":"uuid","nullable":true},"snapshot":{"type":"object","properties":{"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"schoolName":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","schoolName","smid"],"additionalProperties":false},"term":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"schoolYearName":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"}},"required":["id","name","schoolYearName","startDate","endDate"],"additionalProperties":false},"courses":{"type":"array","items":{"type":"object","properties":{"sectionId":{"type":"string","format":"uuid"},"sectionCode":{"type":"string"},"courseCode":{"type":"string"},"courseName":{"type":"string"},"teacherName":{"type":"string","nullable":true},"percentGrade":{"type":"number","nullable":true},"letterGrade":{"type":"string","nullable":true},"gpaValue":{"type":"number","nullable":true},"missingAssignments":{"type":"integer"},"categoryBreakdown":{"type":"object","additionalProperties":{}},"comment":{"type":"string","nullable":true},"commentSource":{"type":"string","nullable":true}},"required":["sectionId","sectionCode","courseCode","courseName","teacherName","percentGrade","letterGrade","gpaValue","missingAssignments","categoryBreakdown","comment","commentSource"],"additionalProperties":false}},"attendance":{"type":"object","properties":{"present":{"type":"integer"},"absent":{"type":"integer"},"tardy":{"type":"integer"},"excused":{"type":"integer"},"total":{"type":"integer"},"rate":{"type":"number","nullable":true}},"required":["present","absent","tardy","excused","total","rate"],"additionalProperties":false},"summary":{"type":"object","properties":{"termGpa":{"type":"number","nullable":true},"termGpaWeighted":{"type":"number","nullable":true},"creditsAttempted":{"type":"number"},"totalMissing":{"type":"integer"},"coursesCount":{"type":"integer"}},"required":["termGpa","termGpaWeighted","creditsAttempted","totalMissing","coursesCount"],"additionalProperties":false}},"required":["student","term","courses","attendance","summary"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","termId","status","lockedAt","publishedAt","generatedByUserId","snapshot","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/sections/{id}/report-comments":{"get":{"summary":"List teacher comments for all students in a section + term","tags":["Report cards"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"termId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"comment":{"type":"string"},"source":{"type":"string"}},"required":["studentPersonId","comment","source"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/sections/{sectionId}/report-comments/{studentId}":{"put":{"summary":"Save / update a teacher comment for one student in one section","tags":["Report cards"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"termId":{"type":"string","format":"uuid"},"comment":{"type":"string","minLength":1,"maxLength":2000},"source":{"type":"string","enum":["teacher","ai-draft","ai-approved"],"default":"teacher"},"aiCitations":{"type":"array","items":{}}},"required":["termId","comment"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"sectionId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"studentId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/students/{id}/graduation-progress":{"get":{"summary":"Progress-to-graduation for a specific student (registrar / counselor view)","tags":["Graduation"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","smid"],"additionalProperties":false},"classYear":{"type":"integer"},"stateCode":{"type":"string"},"totals":{"type":"object","properties":{"required":{"type":"number"},"earned":{"type":"number"},"waived":{"type":"number"},"remaining":{"type":"number"},"percentComplete":{"type":"integer"}},"required":["required","earned","waived","remaining","percentComplete"],"additionalProperties":false},"subjects":{"type":"array","items":{"type":"object","properties":{"subjectArea":{"type":"string"},"label":{"type":"string"},"required":{"type":"number"},"earned":{"type":"number"},"waived":{"type":"number"},"remaining":{"type":"number"},"status":{"type":"string","enum":["met","on-track","short"]}},"required":["subjectArea","label","required","earned","waived","remaining","status"],"additionalProperties":false}},"waivers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subjectArea":{"type":"string"},"creditsWaived":{"type":"number"},"reason":{"type":"string"},"waivedByUserId":{"type":"string","nullable":true},"occurredAt":{"type":"string","format":"date-time"}},"required":["id","subjectArea","creditsWaived","reason","waivedByUserId","occurredAt"],"additionalProperties":false}},"overallStatus":{"type":"string","enum":["met","on-track","at-risk","short"]}},"required":["student","classYear","stateCode","totals","subjects","waivers","overallStatus"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/student/me/graduation-progress":{"get":{"summary":"Current student’s own progress-to-graduation","tags":["Graduation"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","smid"],"additionalProperties":false},"classYear":{"type":"integer"},"stateCode":{"type":"string"},"totals":{"type":"object","properties":{"required":{"type":"number"},"earned":{"type":"number"},"waived":{"type":"number"},"remaining":{"type":"number"},"percentComplete":{"type":"integer"}},"required":["required","earned","waived","remaining","percentComplete"],"additionalProperties":false},"subjects":{"type":"array","items":{"type":"object","properties":{"subjectArea":{"type":"string"},"label":{"type":"string"},"required":{"type":"number"},"earned":{"type":"number"},"waived":{"type":"number"},"remaining":{"type":"number"},"status":{"type":"string","enum":["met","on-track","short"]}},"required":["subjectArea","label","required","earned","waived","remaining","status"],"additionalProperties":false}},"waivers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subjectArea":{"type":"string"},"creditsWaived":{"type":"number"},"reason":{"type":"string"},"waivedByUserId":{"type":"string","nullable":true},"occurredAt":{"type":"string","format":"date-time"}},"required":["id","subjectArea","creditsWaived","reason","waivedByUserId","occurredAt"],"additionalProperties":false}},"overallStatus":{"type":"string","enum":["met","on-track","at-risk","short"]}},"required":["student","classYear","stateCode","totals","subjects","waivers","overallStatus"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/graduation/seniors":{"get":{"summary":"Senior roster with progress + status (registrar clearance view)","tags":["Graduation"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"smid":{"type":"string","nullable":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"classYear":{"type":"integer"},"totals":{"type":"object","properties":{"required":{"type":"number"},"earned":{"type":"number"},"waived":{"type":"number"},"remaining":{"type":"number"},"percentComplete":{"type":"integer"}},"required":["required","earned","waived","remaining","percentComplete"],"additionalProperties":false},"overallStatus":{"type":"string","enum":["met","on-track","at-risk","short"]},"subjectsShort":{"type":"integer"}},"required":["studentPersonId","smid","firstName","lastName","classYear","totals","overallStatus","subjectsShort"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/students/{id}/graduation-waivers":{"post":{"summary":"Waive a subject-area credit requirement for a student","tags":["Graduation"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subjectArea":{"type":"string","minLength":1,"maxLength":50},"creditsWaived":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":60},"reason":{"type":"string","minLength":5,"maxLength":500}},"required":["subjectArea","creditsWaived","reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"}},"required":["eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/504-plans":{"get":{"summary":"List every 504 plan in the district","tags":["Section 504"],"parameters":[{"schema":{"type":"string","enum":["draft","active","expired","archived"]},"in":"query","name":"status","required":false},{"schema":{"type":"integer","minimum":1,"maximum":365},"in":"query","name":"reviewWithinDays","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"smid":{"type":"string","nullable":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"status":{"type":"string"},"disability":{"type":"string"},"majorLifeActivity":{"type":"string"},"planStartDate":{"type":"string"},"planEndDate":{"type":"string"},"nextReviewDate":{"type":"string","nullable":true},"accommodationCount":{"type":"integer"},"reviewDue":{"type":"string","enum":["ok","upcoming","overdue"]},"daysUntilReview":{"type":"integer","nullable":true}},"required":["id","studentPersonId","smid","firstName","lastName","gradeLevel","status","disability","majorLifeActivity","planStartDate","planEndDate","nextReviewDate","accommodationCount","reviewDue","daysUntilReview"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Draft a new 504 plan after eligibility determination","tags":["Section 504"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"disability":{"type":"string","minLength":2,"maxLength":500},"majorLifeActivity":{"type":"string","minLength":2,"maxLength":300},"eligibilityDate":{"type":"string","format":"date"},"planStartDate":{"type":"string","format":"date"},"planEndDate":{"type":"string","format":"date"},"caseManagerPersonId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","maxLength":5000,"nullable":true}},"required":["studentPersonId","disability","majorLifeActivity","eligibilityDate","planStartDate","planEndDate"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/students/{id}/504-plans":{"get":{"summary":"Plans for a specific student (current + history)","tags":["Section 504"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","smid"],"additionalProperties":false},"status":{"type":"string"},"disability":{"type":"string"},"majorLifeActivity":{"type":"string"},"eligibilityDate":{"type":"string"},"planStartDate":{"type":"string"},"planEndDate":{"type":"string"},"lastReviewDate":{"type":"string","nullable":true},"nextReviewDate":{"type":"string","nullable":true},"caseManagerPersonId":{"type":"string","format":"uuid","nullable":true},"caseManagerName":{"type":"string","nullable":true},"parentalConsentOn":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"accommodations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string"},"description":{"type":"string"},"frequency":{"type":"string"},"providerRole":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","category","description","frequency","providerRole","startDate","endDate","notes","isActive"],"additionalProperties":false}},"reviewDue":{"type":"string","enum":["ok","upcoming","overdue"]},"daysUntilReview":{"type":"integer","nullable":true}},"required":["id","student","status","disability","majorLifeActivity","eligibilityDate","planStartDate","planEndDate","lastReviewDate","nextReviewDate","caseManagerPersonId","caseManagerName","parentalConsentOn","notes","accommodations","reviewDue","daysUntilReview"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/student/me/504-plans":{"get":{"summary":"Current student’s own 504 plans","tags":["Section 504"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","smid"],"additionalProperties":false},"status":{"type":"string"},"disability":{"type":"string"},"majorLifeActivity":{"type":"string"},"eligibilityDate":{"type":"string"},"planStartDate":{"type":"string"},"planEndDate":{"type":"string"},"lastReviewDate":{"type":"string","nullable":true},"nextReviewDate":{"type":"string","nullable":true},"caseManagerPersonId":{"type":"string","format":"uuid","nullable":true},"caseManagerName":{"type":"string","nullable":true},"parentalConsentOn":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"accommodations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string"},"description":{"type":"string"},"frequency":{"type":"string"},"providerRole":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","category","description","frequency","providerRole","startDate","endDate","notes","isActive"],"additionalProperties":false}},"reviewDue":{"type":"string","enum":["ok","upcoming","overdue"]},"daysUntilReview":{"type":"integer","nullable":true}},"required":["id","student","status","disability","majorLifeActivity","eligibilityDate","planStartDate","planEndDate","lastReviewDate","nextReviewDate","caseManagerPersonId","caseManagerName","parentalConsentOn","notes","accommodations","reviewDue","daysUntilReview"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/504-plans/{id}":{"get":{"summary":"Single plan with accommodations","tags":["Section 504"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","smid"],"additionalProperties":false},"status":{"type":"string"},"disability":{"type":"string"},"majorLifeActivity":{"type":"string"},"eligibilityDate":{"type":"string"},"planStartDate":{"type":"string"},"planEndDate":{"type":"string"},"lastReviewDate":{"type":"string","nullable":true},"nextReviewDate":{"type":"string","nullable":true},"caseManagerPersonId":{"type":"string","format":"uuid","nullable":true},"caseManagerName":{"type":"string","nullable":true},"parentalConsentOn":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"accommodations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string"},"description":{"type":"string"},"frequency":{"type":"string"},"providerRole":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","category","description","frequency","providerRole","startDate","endDate","notes","isActive"],"additionalProperties":false}},"reviewDue":{"type":"string","enum":["ok","upcoming","overdue"]},"daysUntilReview":{"type":"integer","nullable":true}},"required":["id","student","status","disability","majorLifeActivity","eligibilityDate","planStartDate","planEndDate","lastReviewDate","nextReviewDate","caseManagerPersonId","caseManagerName","parentalConsentOn","notes","accommodations","reviewDue","daysUntilReview"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update plan metadata (status, end date, notes)","tags":["Section 504"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["draft","active","expired","archived"]},"planEndDate":{"type":"string","format":"date"},"nextReviewDate":{"type":"string","format":"date","nullable":true},"caseManagerPersonId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","maxLength":5000,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/504-plans/{id}/review":{"post":{"summary":"Record the annual review meeting outcome","tags":["Section 504"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reviewDate":{"type":"string","format":"date"},"nextReviewDate":{"type":"string","format":"date"},"outcome":{"type":"string","enum":["continued","revised","terminated"]},"notes":{"type":"string","maxLength":5000}},"required":["reviewDate","nextReviewDate","outcome"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/504-plans/{id}/accommodations":{"post":{"summary":"Add an accommodation to a plan","tags":["Section 504"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","enum":["testing","instructional","environmental","behavioral","health","assistive-tech"]},"description":{"type":"string","minLength":3,"maxLength":2000},"frequency":{"type":"string","enum":["per-class","daily","as-needed","testing-only","weekly"]},"providerRole":{"type":"string","enum":["teacher","nurse","counselor","case-manager","administrator"]},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","maxLength":2000,"nullable":true}},"required":["category","description","frequency","providerRole","startDate"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/504-plans/{planId}/accommodations/{accId}/remove":{"post":{"summary":"Deactivate an accommodation (soft-remove)","tags":["Section 504"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"planId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"accId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/teacher/sections/{id}/accommodations":{"get":{"summary":"Accommodations for the students in one of my sections","tags":["Section 504"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"planId":{"type":"string","format":"uuid"},"disability":{"type":"string"},"accommodations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string"},"description":{"type":"string"},"frequency":{"type":"string"},"providerRole":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","category","description","frequency","providerRole","startDate","endDate","notes","isActive"],"additionalProperties":false}}},"required":["studentPersonId","firstName","lastName","gradeLevel","planId","disability","accommodations"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/truancy/cases":{"get":{"summary":"District truancy caseload","tags":["Truancy"],"parameters":[{"schema":{"type":"string","maxLength":30},"in":"query","name":"status","required":false},{"schema":{"type":"string","maxLength":30},"in":"query","name":"stage","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"smid":{"type":"string","nullable":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"status":{"type":"string"},"currentStage":{"type":"string"},"unexcusedCount":{"type":"integer"},"schoolYearName":{"type":"string"},"openedAt":{"type":"string","format":"date-time"},"lastLetterType":{"type":"string","nullable":true},"lastLetterSentAt":{"type":"string","format":"date-time","nullable":true},"lastLetterAcknowledgedAt":{"type":"string","format":"date-time","nullable":true},"courtReferralReady":{"type":"boolean"}},"required":["id","studentPersonId","smid","firstName","lastName","gradeLevel","status","currentStage","unexcusedCount","schoolYearName","openedAt","lastLetterType","lastLetterSentAt","lastLetterAcknowledgedAt","courtReferralReady"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/truancy/cases/{id}":{"get":{"summary":"One case with full letter history","tags":["Truancy"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"smid":{"type":"string","nullable":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"status":{"type":"string"},"currentStage":{"type":"string"},"unexcusedCount":{"type":"integer"},"schoolYearName":{"type":"string"},"openedAt":{"type":"string","format":"date-time"},"lastLetterType":{"type":"string","nullable":true},"lastLetterSentAt":{"type":"string","format":"date-time","nullable":true},"lastLetterAcknowledgedAt":{"type":"string","format":"date-time","nullable":true},"courtReferralReady":{"type":"boolean"},"letters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"letterType":{"type":"string"},"unexcusedCountAtSend":{"type":"integer"},"generatedAt":{"type":"string","format":"date-time"},"sentAt":{"type":"string","format":"date-time","nullable":true},"deliveryMethod":{"type":"string"},"parentAcknowledgedAt":{"type":"string","format":"date-time","nullable":true},"bodyMarkdown":{"type":"string"}},"required":["id","letterType","unexcusedCountAtSend","generatedAt","sentAt","deliveryMethod","parentAcknowledgedAt","bodyMarkdown"],"additionalProperties":false}},"notes":{"type":"string","nullable":true},"resolution":{"type":"string","nullable":true}},"required":["id","studentPersonId","smid","firstName","lastName","gradeLevel","status","currentStage","unexcusedCount","schoolYearName","openedAt","lastLetterType","lastLetterSentAt","lastLetterAcknowledgedAt","courtReferralReady","letters","notes","resolution"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/truancy/policy":{"get":{"summary":"District truancy policy (thresholds + letter templates)","tags":["Truancy"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"letter1Threshold":{"type":"integer"},"letter2Threshold":{"type":"integer"},"courtReferralThreshold":{"type":"integer"},"letter1Template":{"type":"string"},"letter2Template":{"type":"string"},"courtReferralTemplate":{"type":"string"}},"required":["id","letter1Threshold","letter2Threshold","courtReferralThreshold","letter1Template","letter2Template","courtReferralTemplate"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update thresholds or letter templates","tags":["Truancy"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"letter1Threshold":{"type":"integer","minimum":1,"maximum":100},"letter2Threshold":{"type":"integer","minimum":1,"maximum":100},"courtReferralThreshold":{"type":"integer","minimum":1,"maximum":100},"letter1Template":{"type":"string","minLength":20,"maxLength":10000},"letter2Template":{"type":"string","minLength":20,"maxLength":10000},"courtReferralTemplate":{"type":"string","minLength":20,"maxLength":10000}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/truancy/evaluate":{"post":{"summary":"Scan attendance and open/advance cases","tags":["Truancy"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"casesOpened":{"type":"integer"},"casesAdvanced":{"type":"integer"},"studentsScanned":{"type":"integer"}},"required":["casesOpened","casesAdvanced","studentsScanned"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/truancy/cases/{id}/generate-letter":{"post":{"summary":"Draft a letter of the specified tier for the case","tags":["Truancy"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"letterType":{"type":"string","enum":["letter1","letter2","court-referral"]}},"required":["letterType"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"letterId":{"type":"string","format":"uuid"},"bodyMarkdown":{"type":"string"},"unexcusedCountAtSend":{"type":"integer"}},"required":["letterId","bodyMarkdown","unexcusedCountAtSend"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/truancy/letters/{id}/send":{"post":{"summary":"Mark a generated letter as sent via the chosen channel","tags":["Truancy"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"deliveryMethod":{"type":"string","enum":["mail","email","hand","home-visit"]}},"required":["deliveryMethod"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/truancy/letters/{id}/acknowledge":{"post":{"summary":"Record parent acknowledgement of a truancy letter","tags":["Truancy"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"acknowledgedByPersonId":{"type":"string","format":"uuid"}},"required":["acknowledgedByPersonId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/truancy/cases/{id}/resolve":{"post":{"summary":"Resolve a truancy case (attendance restored, transfer, etc.)","tags":["Truancy"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolution":{"type":"string","minLength":3,"maxLength":500}},"required":["resolution"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/counselors/me/caseload":{"get":{"summary":"List the calling counselor's active caseload","tags":["Counselor"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"counselorPersonId":{"type":"string","format":"uuid"},"counselorName":{"type":"string"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"studentLocalId":{"type":"string","nullable":true},"studentSmid":{"type":"string","nullable":true},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"isPrimary":{"type":"boolean"},"notes":{"type":"string","nullable":true}},"required":["id","counselorPersonId","counselorName","studentPersonId","studentName","studentLocalId","studentSmid","schoolId","schoolName","startDate","endDate","isPrimary","notes"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/counselors/{counselorPersonId}/caseload":{"get":{"summary":"List active caseload for a specific counselor","tags":["Counselor"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"counselorPersonId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"counselorPersonId":{"type":"string","format":"uuid"},"counselorName":{"type":"string"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"studentLocalId":{"type":"string","nullable":true},"studentSmid":{"type":"string","nullable":true},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"isPrimary":{"type":"boolean"},"notes":{"type":"string","nullable":true}},"required":["id","counselorPersonId","counselorName","studentPersonId","studentName","studentLocalId","studentSmid","schoolId","schoolName","startDate","endDate","isPrimary","notes"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/counselors/unassigned":{"get":{"summary":"List active students with no current counselor assignment","tags":["Counselor"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","maxLength":100},"in":"query","name":"search","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"studentLocalId":{"type":"string","nullable":true},"studentSmid":{"type":"string","nullable":true},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"gradeLevel":{"type":"string","nullable":true}},"required":["studentPersonId","studentName","studentLocalId","studentSmid","schoolId","schoolName","gradeLevel"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/counselors/caseload/assign":{"post":{"summary":"Assign a student to a counselor","tags":["Counselor"],"description":"Idempotent. If the same counselor↔student pair already has an active row, the existing row is end-dated and a new row is created so the change is auditable.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"counselorPersonId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"startDate":{"type":"string","format":"date"},"isPrimary":{"type":"boolean","default":true},"notes":{"type":"string","maxLength":1000,"nullable":true}},"required":["counselorPersonId","studentPersonId"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"counselorPersonId":{"type":"string","format":"uuid"},"counselorName":{"type":"string"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"studentLocalId":{"type":"string","nullable":true},"studentSmid":{"type":"string","nullable":true},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"isPrimary":{"type":"boolean"},"notes":{"type":"string","nullable":true}},"required":["id","counselorPersonId","counselorName","studentPersonId","studentName","studentLocalId","studentSmid","schoolId","schoolName","startDate","endDate","isPrimary","notes"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/counselors/caseload/{assignmentId}/unassign":{"post":{"summary":"End a counselor assignment","tags":["Counselor"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"endDate":{"type":"string","format":"date"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"assignmentId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/counselors/caseload/request":{"post":{"summary":"Counselor requests assignment of a specific student","tags":["Counselor"],"description":"Counselors cannot self-assign; this endpoint emits an event so a principal/school_admin can review and action it.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["studentPersonId","reason"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"requested":{"type":"boolean","enum":[true]},"eventId":{"type":"string","format":"uuid"}},"required":["requested","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/referrals":{"get":{"summary":"List SPED referrals","tags":["IEP"],"parameters":[{"schema":{"type":"string","enum":["pending","in-evaluation","eligible","ineligible","withdrawn"]},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"smid":{"type":"string","nullable":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"referralDate":{"type":"string"},"referralSource":{"type":"string"},"status":{"type":"string"},"concerns":{"type":"string"},"evaluationsCompleted":{"type":"integer"},"evaluationsTotal":{"type":"integer"},"hasActiveIep":{"type":"boolean"}},"required":["id","studentPersonId","smid","firstName","lastName","gradeLevel","referralDate","referralSource","status","concerns","evaluationsCompleted","evaluationsTotal","hasActiveIep"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Open a new SPED referral (Child Find)","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"referralDate":{"type":"string","format":"date"},"referralSource":{"type":"string","enum":["teacher","parent","counselor","admin","doctor","outside-agency"]},"concerns":{"type":"string","minLength":10,"maxLength":5000},"referredByPersonId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","maxLength":5000,"nullable":true}},"required":["studentPersonId","referralDate","referralSource","concerns"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/iep/referrals/{id}":{"get":{"summary":"One referral with evaluations","tags":["IEP"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","smid"],"additionalProperties":false},"referralDate":{"type":"string"},"referralSource":{"type":"string"},"referredByPersonId":{"type":"string","format":"uuid","nullable":true},"concerns":{"type":"string"},"status":{"type":"string"},"parentalConsentOn":{"type":"string","format":"date-time","nullable":true},"eligibilityDecisionDate":{"type":"string","nullable":true},"eligibilityDecision":{"type":"string","nullable":true},"eligibilityRationale":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"evaluations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"evaluationType":{"type":"string"},"evaluatorName":{"type":"string","nullable":true},"scheduledDate":{"type":"string","nullable":true},"completedDate":{"type":"string","nullable":true},"status":{"type":"string"},"findings":{"type":"string","nullable":true}},"required":["id","evaluationType","evaluatorName","scheduledDate","completedDate","status","findings"],"additionalProperties":false}},"iepRecordIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","student","referralDate","referralSource","referredByPersonId","concerns","status","parentalConsentOn","eligibilityDecisionDate","eligibilityDecision","eligibilityRationale","notes","evaluations","iepRecordIds"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update referral (status, consent, eligibility decision, notes)","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","in-evaluation","eligible","ineligible","withdrawn"]},"parentalConsentOn":{"type":"string","format":"date-time","nullable":true},"eligibilityDecisionDate":{"type":"string","format":"date","nullable":true},"eligibilityDecision":{"type":"string","enum":["eligible","ineligible"],"nullable":true},"eligibilityRationale":{"type":"string","maxLength":5000,"nullable":true},"notes":{"type":"string","maxLength":5000,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/referrals/{id}/evaluations":{"post":{"summary":"Schedule an evaluation on a referral","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"evaluationType":{"type":"string","enum":["cognitive","academic","speech-language","ot-pt","behavioral","adaptive","medical","other"]},"evaluatorName":{"type":"string","maxLength":200,"nullable":true},"evaluatorPersonId":{"type":"string","format":"uuid","nullable":true},"scheduledDate":{"type":"string","format":"date","nullable":true}},"required":["evaluationType"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/evaluations/{id}":{"patch":{"summary":"Update an evaluation (status, findings, completed date)","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["scheduled","in-progress","completed","cancelled"]},"completedDate":{"type":"string","format":"date","nullable":true},"findings":{"type":"string","maxLength":20000,"nullable":true},"reportUrl":{"type":"string","format":"uri","nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/plans":{"get":{"summary":"List IEPs (district caseload)","tags":["IEP"],"parameters":[{"schema":{"type":"string","enum":["draft","active","expired","archived"]},"in":"query","name":"status","required":false},{"schema":{"type":"integer","minimum":1,"maximum":365},"in":"query","name":"reviewWithinDays","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"smid":{"type":"string","nullable":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"status":{"type":"string"},"disabilityCategory":{"type":"string","nullable":true},"planStart":{"type":"string"},"planEnd":{"type":"string"},"nextReviewDate":{"type":"string","nullable":true},"reevaluationDueDate":{"type":"string","nullable":true},"goalCount":{"type":"integer"},"accommodationCount":{"type":"integer"},"reviewDue":{"type":"string","enum":["ok","upcoming","overdue"]},"daysUntilReview":{"type":"integer","nullable":true},"reevaluationDue":{"type":"string","enum":["ok","upcoming","overdue"]}},"required":["id","studentPersonId","smid","firstName","lastName","gradeLevel","status","disabilityCategory","planStart","planEnd","nextReviewDate","reevaluationDueDate","goalCount","accommodationCount","reviewDue","daysUntilReview","reevaluationDue"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Draft a new IEP after eligibility determination","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"referralId":{"type":"string","format":"uuid","nullable":true},"disabilityCategory":{"type":"string","maxLength":50},"secondaryDisabilityCategory":{"type":"string","maxLength":50,"nullable":true},"planStart":{"type":"string","format":"date"},"planEnd":{"type":"string","format":"date"},"caseManagerId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","maxLength":10000,"nullable":true}},"required":["studentPersonId","planStart","planEnd"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/iep/plans/{id}":{"get":{"summary":"Single IEP with goals, services, accommodations","tags":["IEP"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","smid"],"additionalProperties":false},"referralId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string"},"disabilityCategory":{"type":"string","nullable":true},"secondaryDisabilityCategory":{"type":"string","nullable":true},"planStart":{"type":"string"},"planEnd":{"type":"string"},"lastReviewDate":{"type":"string","nullable":true},"nextReviewDate":{"type":"string","nullable":true},"reevaluationDueDate":{"type":"string","nullable":true},"caseManagerId":{"type":"string","format":"uuid","nullable":true},"caseManagerName":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"goals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"goalArea":{"type":"string"},"statement":{"type":"string"},"measurableCriteria":{"type":"string"},"progressInterval":{"type":"string"},"targetDate":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","goalArea","statement","measurableCriteria","progressInterval","targetDate","isActive"],"additionalProperties":false}},"services":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceType":{"type":"string"},"providerRole":{"type":"string"},"providerName":{"type":"string","nullable":true},"frequencyMinutes":{"type":"integer"},"frequencyUnit":{"type":"string"},"settingCode":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"notes":{"type":"string","nullable":true}},"required":["id","serviceType","providerRole","providerName","frequencyMinutes","frequencyUnit","settingCode","startDate","endDate","isActive","notes"],"additionalProperties":false}},"accommodations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string"},"description":{"type":"string"},"frequency":{"type":"string"},"providerRole":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","category","description","frequency","providerRole","startDate","endDate","notes","isActive"],"additionalProperties":false}},"reviewDue":{"type":"string","enum":["ok","upcoming","overdue"]},"daysUntilReview":{"type":"integer","nullable":true},"reevaluationDue":{"type":"string","enum":["ok","upcoming","overdue"]},"daysUntilReevaluation":{"type":"integer","nullable":true}},"required":["id","student","referralId","status","disabilityCategory","secondaryDisabilityCategory","planStart","planEnd","lastReviewDate","nextReviewDate","reevaluationDueDate","caseManagerId","caseManagerName","notes","goals","services","accommodations","reviewDue","daysUntilReview","reevaluationDue","daysUntilReevaluation"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update IEP metadata (status, disability, dates, notes)","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["draft","active","expired","archived"]},"disabilityCategory":{"type":"string","maxLength":50,"nullable":true},"secondaryDisabilityCategory":{"type":"string","maxLength":50,"nullable":true},"planEnd":{"type":"string","format":"date"},"nextReviewDate":{"type":"string","format":"date","nullable":true},"reevaluationDueDate":{"type":"string","format":"date","nullable":true},"caseManagerId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","maxLength":10000,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/students/{id}/plans":{"get":{"summary":"IEPs for a specific student (history)","tags":["IEP"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","smid"],"additionalProperties":false},"referralId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string"},"disabilityCategory":{"type":"string","nullable":true},"secondaryDisabilityCategory":{"type":"string","nullable":true},"planStart":{"type":"string"},"planEnd":{"type":"string"},"lastReviewDate":{"type":"string","nullable":true},"nextReviewDate":{"type":"string","nullable":true},"reevaluationDueDate":{"type":"string","nullable":true},"caseManagerId":{"type":"string","format":"uuid","nullable":true},"caseManagerName":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"goals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"goalArea":{"type":"string"},"statement":{"type":"string"},"measurableCriteria":{"type":"string"},"progressInterval":{"type":"string"},"targetDate":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","goalArea","statement","measurableCriteria","progressInterval","targetDate","isActive"],"additionalProperties":false}},"services":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceType":{"type":"string"},"providerRole":{"type":"string"},"providerName":{"type":"string","nullable":true},"frequencyMinutes":{"type":"integer"},"frequencyUnit":{"type":"string"},"settingCode":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"notes":{"type":"string","nullable":true}},"required":["id","serviceType","providerRole","providerName","frequencyMinutes","frequencyUnit","settingCode","startDate","endDate","isActive","notes"],"additionalProperties":false}},"accommodations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string"},"description":{"type":"string"},"frequency":{"type":"string"},"providerRole":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","category","description","frequency","providerRole","startDate","endDate","notes","isActive"],"additionalProperties":false}},"reviewDue":{"type":"string","enum":["ok","upcoming","overdue"]},"daysUntilReview":{"type":"integer","nullable":true},"reevaluationDue":{"type":"string","enum":["ok","upcoming","overdue"]},"daysUntilReevaluation":{"type":"integer","nullable":true}},"required":["id","student","referralId","status","disabilityCategory","secondaryDisabilityCategory","planStart","planEnd","lastReviewDate","nextReviewDate","reevaluationDueDate","caseManagerId","caseManagerName","notes","goals","services","accommodations","reviewDue","daysUntilReview","reevaluationDue","daysUntilReevaluation"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/iep/student/me/plans":{"get":{"summary":"Current student’s own IEPs","tags":["IEP"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"student":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"smid":{"type":"string","nullable":true}},"required":["id","firstName","lastName","gradeLevel","smid"],"additionalProperties":false},"referralId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string"},"disabilityCategory":{"type":"string","nullable":true},"secondaryDisabilityCategory":{"type":"string","nullable":true},"planStart":{"type":"string"},"planEnd":{"type":"string"},"lastReviewDate":{"type":"string","nullable":true},"nextReviewDate":{"type":"string","nullable":true},"reevaluationDueDate":{"type":"string","nullable":true},"caseManagerId":{"type":"string","format":"uuid","nullable":true},"caseManagerName":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"goals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"goalArea":{"type":"string"},"statement":{"type":"string"},"measurableCriteria":{"type":"string"},"progressInterval":{"type":"string"},"targetDate":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","goalArea","statement","measurableCriteria","progressInterval","targetDate","isActive"],"additionalProperties":false}},"services":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serviceType":{"type":"string"},"providerRole":{"type":"string"},"providerName":{"type":"string","nullable":true},"frequencyMinutes":{"type":"integer"},"frequencyUnit":{"type":"string"},"settingCode":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"notes":{"type":"string","nullable":true}},"required":["id","serviceType","providerRole","providerName","frequencyMinutes","frequencyUnit","settingCode","startDate","endDate","isActive","notes"],"additionalProperties":false}},"accommodations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string"},"description":{"type":"string"},"frequency":{"type":"string"},"providerRole":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","category","description","frequency","providerRole","startDate","endDate","notes","isActive"],"additionalProperties":false}},"reviewDue":{"type":"string","enum":["ok","upcoming","overdue"]},"daysUntilReview":{"type":"integer","nullable":true},"reevaluationDue":{"type":"string","enum":["ok","upcoming","overdue"]},"daysUntilReevaluation":{"type":"integer","nullable":true}},"required":["id","student","referralId","status","disabilityCategory","secondaryDisabilityCategory","planStart","planEnd","lastReviewDate","nextReviewDate","reevaluationDueDate","caseManagerId","caseManagerName","notes","goals","services","accommodations","reviewDue","daysUntilReview","reevaluationDue","daysUntilReevaluation"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/iep/plans/{id}/review":{"post":{"summary":"Record the annual review meeting outcome","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reviewDate":{"type":"string","format":"date"},"nextReviewDate":{"type":"string","format":"date"},"outcome":{"type":"string","enum":["continued","revised","terminated"]},"notes":{"type":"string","maxLength":10000}},"required":["reviewDate","nextReviewDate","outcome"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/plans/{id}/goals":{"post":{"summary":"Add a measurable annual goal to an IEP","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"goalArea":{"type":"string","enum":["academic","behavioral","social-emotional","communication","adaptive","motor","functional","transition"]},"statement":{"type":"string","minLength":5,"maxLength":5000},"measurableCriteria":{"type":"string","minLength":5,"maxLength":5000},"progressInterval":{"type":"string","enum":["quarterly","trimester","monthly","weekly"],"default":"quarterly"},"targetDate":{"type":"string","format":"date","nullable":true}},"required":["goalArea","statement","measurableCriteria"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/goals/{id}/retire":{"post":{"summary":"Deactivate a goal (kept for history)","tags":["IEP"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/plans/{id}/services":{"post":{"summary":"Add a related service (SLP, OT, PT, counseling, …) to an IEP","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceType":{"type":"string","enum":["speech-language","occupational-therapy","physical-therapy","counseling","nursing","audiology","orientation-mobility","transportation","behavioral-support","interpretation","other"]},"providerRole":{"type":"string","maxLength":50},"providerName":{"type":"string","maxLength":200,"nullable":true},"frequencyMinutes":{"type":"integer","minimum":5,"maximum":6000},"frequencyUnit":{"type":"string","enum":["per-week","per-month","per-year"]},"settingCode":{"type":"string","enum":["general-ed","special-ed-pullout","separate-class","community","other"],"default":"general-ed"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","maxLength":2000,"nullable":true}},"required":["serviceType","providerRole","frequencyMinutes","frequencyUnit","startDate"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/services/{id}/retire":{"post":{"summary":"Deactivate an IEP service","tags":["IEP"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/plans/{id}/accommodations":{"post":{"summary":"Add an accommodation to an IEP","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","enum":["testing","instructional","environmental","behavioral","health","assistive-tech"]},"description":{"type":"string","minLength":3,"maxLength":2000},"frequency":{"type":"string","enum":["per-class","daily","as-needed","testing-only","weekly"]},"providerRole":{"type":"string","enum":["teacher","nurse","counselor","case-manager","administrator"]},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","maxLength":2000,"nullable":true}},"required":["category","description","frequency","providerRole","startDate"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/accommodations/{id}/remove":{"post":{"summary":"Retire an IEP accommodation with reason","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/teacher/sections/{id}/accommodations":{"get":{"summary":"Active IEP accommodations for students in this section","tags":["IEP"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"iepRecordId":{"type":"string","format":"uuid"},"disabilityCategory":{"type":"string","nullable":true},"accommodations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string"},"description":{"type":"string"},"frequency":{"type":"string"},"providerRole":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","category","description","frequency","providerRole","startDate","endDate","notes","isActive"],"additionalProperties":false}}},"required":["studentPersonId","firstName","lastName","gradeLevel","iepRecordId","disabilityCategory","accommodations"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/iep/plans/{id}/signatures":{"get":{"summary":"List signatures captured against an IEP plan","tags":["IEP"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"iepRecordId":{"type":"string","format":"uuid"},"signerPersonId":{"type":"string","format":"uuid"},"signerRole":{"type":"string"},"signatureType":{"type":"string"},"signedAt":{"type":"string","format":"date-time"},"contentHash":{"type":"string"},"documentUrl":{"type":"string","nullable":true},"attestedName":{"type":"string"},"revokedAt":{"type":"string","format":"date-time","nullable":true},"revokedByPersonId":{"type":"string","format":"uuid","nullable":true},"revocationReason":{"type":"string","nullable":true}},"required":["id","iepRecordId","signerPersonId","signerRole","signatureType","signedAt","contentHash","documentUrl","attestedName","revokedAt","revokedByPersonId","revocationReason"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Capture a typed-name signature against an IEP (consent, agreement, attendance, amendment)","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signerPersonId":{"type":"string","format":"uuid"},"signerRole":{"type":"string","enum":["parent_guardian","student","case_manager","administrator","gen_ed_teacher","special_ed_teacher","related_service_provider","district_rep","lea_rep","evaluator","interpreter","other"]},"signatureType":{"type":"string","enum":["consent_to_evaluate","consent_to_placement","plan_agreement","meeting_attendance","annual_review","amendment"]},"attestedName":{"type":"string","minLength":2,"maxLength":200},"documentUrl":{"type":"string","format":"uri","maxLength":500,"nullable":true},"metadataOverride":{"type":"object","properties":{"userAgent":{"type":"string","maxLength":512},"ipAddress":{"type":"string","maxLength":64}},"additionalProperties":false}},"required":["signerPersonId","signerRole","signatureType","attestedName"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"iepRecordId":{"type":"string","format":"uuid"},"signerPersonId":{"type":"string","format":"uuid"},"signerRole":{"type":"string"},"signatureType":{"type":"string"},"signedAt":{"type":"string","format":"date-time"},"contentHash":{"type":"string"},"documentUrl":{"type":"string","nullable":true},"attestedName":{"type":"string"},"revokedAt":{"type":"string","format":"date-time","nullable":true},"revokedByPersonId":{"type":"string","format":"uuid","nullable":true},"revocationReason":{"type":"string","nullable":true}},"required":["id","iepRecordId","signerPersonId","signerRole","signatureType","signedAt","contentHash","documentUrl","attestedName","revokedAt","revokedByPersonId","revocationReason"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/signatures/{id}/revoke":{"post":{"summary":"Revoke a previously captured IEP signature","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":200}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/plans/{id}/meetings":{"get":{"summary":"List IEP team meetings for a plan","tags":["IEP"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"iepRecordId":{"type":"string","format":"uuid"},"meetingType":{"type":"string"},"scheduledAt":{"type":"string","format":"date-time"},"heldAt":{"type":"string","format":"date-time","nullable":true},"durationMinutes":{"type":"integer","nullable":true},"location":{"type":"string","nullable":true},"locationType":{"type":"string"},"invitedAttendees":{"type":"array","items":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"role":{"type":"string","enum":["parent_guardian","student","case_manager","administrator","gen_ed_teacher","special_ed_teacher","related_service_provider","district_rep","lea_rep","evaluator","interpreter","other"]},"notifiedAt":{"type":"string","format":"date-time"},"joinedAt":{"type":"string","format":"date-time"},"leftAt":{"type":"string","format":"date-time"},"reason":{"type":"string","maxLength":500},"writtenExcusalOn":{"type":"string","format":"date"}},"required":["name","role"],"additionalProperties":false}},"presentAttendees":{"type":"array","items":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"role":{"type":"string","enum":["parent_guardian","student","case_manager","administrator","gen_ed_teacher","special_ed_teacher","related_service_provider","district_rep","lea_rep","evaluator","interpreter","other"]},"notifiedAt":{"type":"string","format":"date-time"},"joinedAt":{"type":"string","format":"date-time"},"leftAt":{"type":"string","format":"date-time"},"reason":{"type":"string","maxLength":500},"writtenExcusalOn":{"type":"string","format":"date"}},"required":["name","role"],"additionalProperties":false}},"excusedAttendees":{"type":"array","items":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"role":{"type":"string","enum":["parent_guardian","student","case_manager","administrator","gen_ed_teacher","special_ed_teacher","related_service_provider","district_rep","lea_rep","evaluator","interpreter","other"]},"notifiedAt":{"type":"string","format":"date-time"},"joinedAt":{"type":"string","format":"date-time"},"leftAt":{"type":"string","format":"date-time"},"reason":{"type":"string","maxLength":500},"writtenExcusalOn":{"type":"string","format":"date"}},"required":["name","role"],"additionalProperties":false}},"agenda":{"type":"string","nullable":true},"minutes":{"type":"string","nullable":true},"decisions":{"type":"array","items":{"type":"object","properties":{"decision":{"type":"string"},"voteOrConsensus":{"type":"string"},"rationale":{"type":"string"}},"required":["decision","voteOrConsensus"],"additionalProperties":false},"nullable":true},"actionItems":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"ownerPersonId":{"type":"string","format":"uuid"},"dueDate":{"type":"string","format":"date"},"completedAt":{"type":"string","format":"date-time"}},"required":["description"],"additionalProperties":false},"nullable":true},"nextMeetingDate":{"type":"string","nullable":true},"noticeSentAt":{"type":"string","format":"date-time","nullable":true},"noticeMethod":{"type":"string","nullable":true},"interpreterProvided":{"type":"boolean"},"interpreterLanguage":{"type":"string","nullable":true},"noticeWindowOk":{"type":"boolean"},"daysNotice":{"type":"integer","nullable":true}},"required":["id","iepRecordId","meetingType","scheduledAt","heldAt","durationMinutes","location","locationType","invitedAttendees","presentAttendees","excusedAttendees","agenda","minutes","decisions","actionItems","nextMeetingDate","noticeSentAt","noticeMethod","interpreterProvided","interpreterLanguage","noticeWindowOk","daysNotice"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Schedule an IEP team meeting (IDEA 10-day notice)","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"meetingType":{"type":"string","enum":["initial_eligibility","initial_plan","annual_review","reevaluation","amendment","transition_planning","manifestation_determination","dismissal","other"]},"scheduledAt":{"type":"string","format":"date-time"},"location":{"type":"string","maxLength":200,"nullable":true},"locationType":{"type":"string","enum":["in_person","video","phone","hybrid"],"default":"in_person"},"invitedAttendees":{"type":"array","items":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"role":{"type":"string","enum":["parent_guardian","student","case_manager","administrator","gen_ed_teacher","special_ed_teacher","related_service_provider","district_rep","lea_rep","evaluator","interpreter","other"]},"notifiedAt":{"type":"string","format":"date-time"},"joinedAt":{"type":"string","format":"date-time"},"leftAt":{"type":"string","format":"date-time"},"reason":{"type":"string","maxLength":500},"writtenExcusalOn":{"type":"string","format":"date"}},"required":["name","role"],"additionalProperties":false},"default":[]},"agenda":{"type":"string","maxLength":10000,"nullable":true},"noticeSentAt":{"type":"string","format":"date-time","nullable":true},"noticeMethod":{"type":"string","enum":["email","portal","postal","hand_delivery","phone"],"nullable":true},"interpreterProvided":{"type":"boolean","default":false},"interpreterLanguage":{"type":"string","maxLength":50,"nullable":true}},"required":["meetingType","scheduledAt"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/meetings/{id}":{"patch":{"summary":"Update meeting attendance / minutes / outcomes. Setting `heldAt` emits IepMeeting.Held.","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scheduledAt":{"type":"string","format":"date-time"},"heldAt":{"type":"string","format":"date-time","nullable":true},"durationMinutes":{"type":"integer","minimum":0,"maximum":1440,"nullable":true},"location":{"type":"string","maxLength":200,"nullable":true},"locationType":{"type":"string","enum":["in_person","video","phone","hybrid"]},"invitedAttendees":{"type":"array","items":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"role":{"type":"string","enum":["parent_guardian","student","case_manager","administrator","gen_ed_teacher","special_ed_teacher","related_service_provider","district_rep","lea_rep","evaluator","interpreter","other"]},"notifiedAt":{"type":"string","format":"date-time"},"joinedAt":{"type":"string","format":"date-time"},"leftAt":{"type":"string","format":"date-time"},"reason":{"type":"string","maxLength":500},"writtenExcusalOn":{"type":"string","format":"date"}},"required":["name","role"],"additionalProperties":false}},"presentAttendees":{"type":"array","items":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"role":{"type":"string","enum":["parent_guardian","student","case_manager","administrator","gen_ed_teacher","special_ed_teacher","related_service_provider","district_rep","lea_rep","evaluator","interpreter","other"]},"notifiedAt":{"type":"string","format":"date-time"},"joinedAt":{"type":"string","format":"date-time"},"leftAt":{"type":"string","format":"date-time"},"reason":{"type":"string","maxLength":500},"writtenExcusalOn":{"type":"string","format":"date"}},"required":["name","role"],"additionalProperties":false}},"excusedAttendees":{"type":"array","items":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"role":{"type":"string","enum":["parent_guardian","student","case_manager","administrator","gen_ed_teacher","special_ed_teacher","related_service_provider","district_rep","lea_rep","evaluator","interpreter","other"]},"notifiedAt":{"type":"string","format":"date-time"},"joinedAt":{"type":"string","format":"date-time"},"leftAt":{"type":"string","format":"date-time"},"reason":{"type":"string","maxLength":500},"writtenExcusalOn":{"type":"string","format":"date"}},"required":["name","role"],"additionalProperties":false}},"agenda":{"type":"string","maxLength":10000,"nullable":true},"minutes":{"type":"string","maxLength":50000,"nullable":true},"decisions":{"type":"array","items":{"type":"object","properties":{"decision":{"type":"string","minLength":1,"maxLength":500},"voteOrConsensus":{"type":"string","minLength":1,"maxLength":50},"rationale":{"type":"string","maxLength":2000}},"required":["decision","voteOrConsensus"],"additionalProperties":false},"nullable":true},"actionItems":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":500},"ownerPersonId":{"type":"string","format":"uuid"},"dueDate":{"type":"string","format":"date"},"completedAt":{"type":"string","format":"date-time"}},"required":["description"],"additionalProperties":false},"nullable":true},"nextMeetingDate":{"type":"string","format":"date","nullable":true},"noticeSentAt":{"type":"string","format":"date-time","nullable":true},"noticeMethod":{"type":"string","enum":["email","portal","postal","hand_delivery","phone"],"nullable":true},"interpreterProvided":{"type":"boolean"},"interpreterLanguage":{"type":"string","maxLength":50,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"iepRecordId":{"type":"string","format":"uuid"},"meetingType":{"type":"string"},"scheduledAt":{"type":"string","format":"date-time"},"heldAt":{"type":"string","format":"date-time","nullable":true},"durationMinutes":{"type":"integer","nullable":true},"location":{"type":"string","nullable":true},"locationType":{"type":"string"},"invitedAttendees":{"type":"array","items":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"role":{"type":"string","enum":["parent_guardian","student","case_manager","administrator","gen_ed_teacher","special_ed_teacher","related_service_provider","district_rep","lea_rep","evaluator","interpreter","other"]},"notifiedAt":{"type":"string","format":"date-time"},"joinedAt":{"type":"string","format":"date-time"},"leftAt":{"type":"string","format":"date-time"},"reason":{"type":"string","maxLength":500},"writtenExcusalOn":{"type":"string","format":"date"}},"required":["name","role"],"additionalProperties":false}},"presentAttendees":{"type":"array","items":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"role":{"type":"string","enum":["parent_guardian","student","case_manager","administrator","gen_ed_teacher","special_ed_teacher","related_service_provider","district_rep","lea_rep","evaluator","interpreter","other"]},"notifiedAt":{"type":"string","format":"date-time"},"joinedAt":{"type":"string","format":"date-time"},"leftAt":{"type":"string","format":"date-time"},"reason":{"type":"string","maxLength":500},"writtenExcusalOn":{"type":"string","format":"date"}},"required":["name","role"],"additionalProperties":false}},"excusedAttendees":{"type":"array","items":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"role":{"type":"string","enum":["parent_guardian","student","case_manager","administrator","gen_ed_teacher","special_ed_teacher","related_service_provider","district_rep","lea_rep","evaluator","interpreter","other"]},"notifiedAt":{"type":"string","format":"date-time"},"joinedAt":{"type":"string","format":"date-time"},"leftAt":{"type":"string","format":"date-time"},"reason":{"type":"string","maxLength":500},"writtenExcusalOn":{"type":"string","format":"date"}},"required":["name","role"],"additionalProperties":false}},"agenda":{"type":"string","nullable":true},"minutes":{"type":"string","nullable":true},"decisions":{"type":"array","items":{"type":"object","properties":{"decision":{"type":"string"},"voteOrConsensus":{"type":"string"},"rationale":{"type":"string"}},"required":["decision","voteOrConsensus"],"additionalProperties":false},"nullable":true},"actionItems":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"ownerPersonId":{"type":"string","format":"uuid"},"dueDate":{"type":"string","format":"date"},"completedAt":{"type":"string","format":"date-time"}},"required":["description"],"additionalProperties":false},"nullable":true},"nextMeetingDate":{"type":"string","nullable":true},"noticeSentAt":{"type":"string","format":"date-time","nullable":true},"noticeMethod":{"type":"string","nullable":true},"interpreterProvided":{"type":"boolean"},"interpreterLanguage":{"type":"string","nullable":true},"noticeWindowOk":{"type":"boolean"},"daysNotice":{"type":"integer","nullable":true}},"required":["id","iepRecordId","meetingType","scheduledAt","heldAt","durationMinutes","location","locationType","invitedAttendees","presentAttendees","excusedAttendees","agenda","minutes","decisions","actionItems","nextMeetingDate","noticeSentAt","noticeMethod","interpreterProvided","interpreterLanguage","noticeWindowOk","daysNotice"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/goals/{id}/progress":{"get":{"summary":"List progress notes for a specific goal","tags":["IEP"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"iepGoalId":{"type":"string","format":"uuid"},"observationDate":{"type":"string"},"reportingPeriod":{"type":"string"},"progressStatus":{"type":"string"},"dataPoint":{"type":"number","nullable":true},"dataPointUnit":{"type":"string","nullable":true},"trialsAdministered":{"type":"integer","nullable":true},"trialsSuccessful":{"type":"integer","nullable":true},"narrative":{"type":"string","nullable":true},"evidenceUrl":{"type":"string","nullable":true},"reportedByPersonId":{"type":"string","format":"uuid"},"reportedByName":{"type":"string","nullable":true},"sharedWithParentAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","iepGoalId","observationDate","reportingPeriod","progressStatus","dataPoint","dataPointUnit","trialsAdministered","trialsSuccessful","narrative","evidenceUrl","reportedByPersonId","reportedByName","sharedWithParentAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Record a progress observation against a goal","tags":["IEP"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"observationDate":{"type":"string","format":"date"},"reportingPeriod":{"type":"string","enum":["Q1","Q2","Q3","Q4","T1","T2","T3","M1","M2","M3","M4","M5","M6","M7","M8","M9","M10","M11","M12","weekly","as_needed"]},"progressStatus":{"type":"string","enum":["not_started","emerging","making_progress","mastered","not_making_progress","regressed","discontinued"]},"dataPoint":{"type":"number","minimum":-1000000,"maximum":1000000,"nullable":true},"dataPointUnit":{"type":"string","maxLength":30,"nullable":true},"trialsAdministered":{"type":"integer","minimum":0,"maximum":10000,"nullable":true},"trialsSuccessful":{"type":"integer","minimum":0,"maximum":10000,"nullable":true},"narrative":{"type":"string","maxLength":10000,"nullable":true},"evidenceUrl":{"type":"string","format":"uri","maxLength":500,"nullable":true}},"required":["observationDate","reportingPeriod","progressStatus"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/plans/{id}/progress":{"get":{"summary":"List all progress notes across every goal on a plan (reverse-chron).","tags":["IEP"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"iepGoalId":{"type":"string","format":"uuid"},"observationDate":{"type":"string"},"reportingPeriod":{"type":"string"},"progressStatus":{"type":"string"},"dataPoint":{"type":"number","nullable":true},"dataPointUnit":{"type":"string","nullable":true},"trialsAdministered":{"type":"integer","nullable":true},"trialsSuccessful":{"type":"integer","nullable":true},"narrative":{"type":"string","nullable":true},"evidenceUrl":{"type":"string","nullable":true},"reportedByPersonId":{"type":"string","format":"uuid"},"reportedByName":{"type":"string","nullable":true},"sharedWithParentAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","iepGoalId","observationDate","reportingPeriod","progressStatus","dataPoint","dataPointUnit","trialsAdministered","trialsSuccessful","narrative","evidenceUrl","reportedByPersonId","reportedByName","sharedWithParentAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/iep/progress-notes/{id}/share-with-parent":{"patch":{"summary":"Mark a progress note as included in a periodic parent report (sets sharedWithParentAt).","tags":["IEP"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"sharedAt":{"type":"string","format":"date-time"}},"required":["ok","sharedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/routes":{"get":{"summary":"List bus routes","tags":["Transportation"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"boolean","default":true},"in":"query","name":"activeOnly","required":false},{"schema":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"in":"query","name":"direction","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"routeNumber":{"type":"string"},"name":{"type":"string"},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"schoolId":{"type":"string","format":"uuid","nullable":true},"busNumber":{"type":"string","nullable":true},"driverName":{"type":"string","nullable":true},"driverPhone":{"type":"string","nullable":true},"capacity":{"type":"integer","nullable":true},"isActive":{"type":"boolean"},"notes":{"type":"string","nullable":true},"stopCount":{"type":"integer"},"activeAssignmentCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","routeNumber","name","direction","schoolId","busNumber","driverName","driverPhone","capacity","isActive","notes","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a bus route (emits BusRouteCreated)","tags":["Transportation"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"routeNumber":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","minLength":1,"maxLength":200},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"],"default":"both"},"schoolId":{"type":"string","format":"uuid"},"busNumber":{"type":"string","maxLength":30},"driverName":{"type":"string","maxLength":200},"driverPhone":{"type":"string","maxLength":30},"capacity":{"type":"integer","exclusiveMinimum":true,"minimum":0},"notes":{"type":"string","maxLength":2000},"stops":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer","minimum":1},"address":{"type":"string","minLength":3,"maxLength":500},"scheduledTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"notes":{"type":"string","maxLength":500}},"required":["sequence","address","scheduledTime"],"additionalProperties":false},"default":[]}},"required":["routeNumber","name"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"routeNumber":{"type":"string"},"name":{"type":"string"},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"schoolId":{"type":"string","format":"uuid","nullable":true},"busNumber":{"type":"string","nullable":true},"driverName":{"type":"string","nullable":true},"driverPhone":{"type":"string","nullable":true},"capacity":{"type":"integer","nullable":true},"isActive":{"type":"boolean"},"notes":{"type":"string","nullable":true},"stopCount":{"type":"integer"},"activeAssignmentCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"stops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"routeId":{"type":"string","format":"uuid"},"sequence":{"type":"integer"},"address":{"type":"string"},"scheduledTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","routeId","sequence","address","scheduledTime","latitude","longitude","notes"],"additionalProperties":false}}},"required":["id","routeNumber","name","direction","schoolId","busNumber","driverName","driverPhone","capacity","isActive","notes","createdAt","updatedAt","stops"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/routes/{id}":{"get":{"summary":"Get a bus route with its stops","tags":["Transportation"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"routeNumber":{"type":"string"},"name":{"type":"string"},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"schoolId":{"type":"string","format":"uuid","nullable":true},"busNumber":{"type":"string","nullable":true},"driverName":{"type":"string","nullable":true},"driverPhone":{"type":"string","nullable":true},"capacity":{"type":"integer","nullable":true},"isActive":{"type":"boolean"},"notes":{"type":"string","nullable":true},"stopCount":{"type":"integer"},"activeAssignmentCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"stops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"routeId":{"type":"string","format":"uuid"},"sequence":{"type":"integer"},"address":{"type":"string"},"scheduledTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","routeId","sequence","address","scheduledTime","latitude","longitude","notes"],"additionalProperties":false}}},"required":["id","routeNumber","name","direction","schoolId","busNumber","driverName","driverPhone","capacity","isActive","notes","createdAt","updatedAt","stops"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Edit a bus route (emits BusRouteUpdated)","tags":["Transportation"],"description":"Passing `stops` replaces the stop list — requires that there be no active assignments on the route. Omit `stops` to keep the current list unchanged.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"routeNumber":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","minLength":1,"maxLength":200},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"schoolId":{"type":"string","format":"uuid","nullable":true},"busNumber":{"type":"string","maxLength":30,"nullable":true},"driverName":{"type":"string","maxLength":200,"nullable":true},"driverPhone":{"type":"string","maxLength":30,"nullable":true},"capacity":{"type":"integer","exclusiveMinimum":true,"minimum":0,"nullable":true},"notes":{"type":"string","maxLength":2000,"nullable":true},"stops":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer","minimum":1},"address":{"type":"string","minLength":3,"maxLength":500},"scheduledTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"notes":{"type":"string","maxLength":500}},"required":["sequence","address","scheduledTime"],"additionalProperties":false}}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"routeNumber":{"type":"string"},"name":{"type":"string"},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"schoolId":{"type":"string","format":"uuid","nullable":true},"busNumber":{"type":"string","nullable":true},"driverName":{"type":"string","nullable":true},"driverPhone":{"type":"string","nullable":true},"capacity":{"type":"integer","nullable":true},"isActive":{"type":"boolean"},"notes":{"type":"string","nullable":true},"stopCount":{"type":"integer"},"activeAssignmentCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"stops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"routeId":{"type":"string","format":"uuid"},"sequence":{"type":"integer"},"address":{"type":"string"},"scheduledTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","routeId","sequence","address","scheduledTime","latitude","longitude","notes"],"additionalProperties":false}}},"required":["id","routeNumber","name","direction","schoolId","busNumber","driverName","driverPhone","capacity","isActive","notes","createdAt","updatedAt","stops"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/routes/{id}/deactivate":{"post":{"summary":"Retire a bus route (emits BusRouteDeactivated)","tags":["Transportation"],"description":"Marks the route inactive so no new assignments can be attached. Existing assignments remain historical. Refuses if the route already has active assignments — end them first.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"routeNumber":{"type":"string"},"name":{"type":"string"},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"schoolId":{"type":"string","format":"uuid","nullable":true},"busNumber":{"type":"string","nullable":true},"driverName":{"type":"string","nullable":true},"driverPhone":{"type":"string","nullable":true},"capacity":{"type":"integer","nullable":true},"isActive":{"type":"boolean"},"notes":{"type":"string","nullable":true},"stopCount":{"type":"integer"},"activeAssignmentCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"stops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"routeId":{"type":"string","format":"uuid"},"sequence":{"type":"integer"},"address":{"type":"string"},"scheduledTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","routeId","sequence","address","scheduledTime","latitude","longitude","notes"],"additionalProperties":false}}},"required":["id","routeNumber","name","direction","schoolId","busNumber","driverName","driverPhone","capacity","isActive","notes","createdAt","updatedAt","stops"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/assignments":{"get":{"summary":"List route assignments","tags":["Transportation"],"description":"Default is active-only (no effectiveTo or effectiveTo in the future). Pass ?activeOnly=false to include history.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"routeId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"boolean","default":true},"in":"query","name":"activeOnly","required":false},{"schema":{"type":"boolean","default":false},"in":"query","name":"specialEdOnly","required":false},{"schema":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"in":"query","name":"direction","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"routeId":{"type":"string","format":"uuid"},"routeNumber":{"type":"string"},"routeName":{"type":"string"},"stopId":{"type":"string","format":"uuid"},"stopSequence":{"type":"integer"},"stopAddress":{"type":"string"},"stopScheduledTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date","nullable":true},"isSpecialEd":{"type":"boolean"},"accommodations":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","routeId","stopId","direction","effectiveFrom","effectiveTo","isSpecialEd","accommodations","notes","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Assign a student to a route (emits StudentAssignedToRoute)","tags":["Transportation"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"routeId":{"type":"string","format":"uuid"},"stopId":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"],"default":"both"},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"},"isSpecialEd":{"type":"boolean","default":false},"accommodations":{"type":"string","maxLength":1000},"notes":{"type":"string","maxLength":1000}},"required":["studentId","routeId","stopId","effectiveFrom"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"routeId":{"type":"string","format":"uuid"},"routeNumber":{"type":"string"},"routeName":{"type":"string"},"stopId":{"type":"string","format":"uuid"},"stopSequence":{"type":"integer"},"stopAddress":{"type":"string"},"stopScheduledTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date","nullable":true},"isSpecialEd":{"type":"boolean"},"accommodations":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","routeId","stopId","direction","effectiveFrom","effectiveTo","isSpecialEd","accommodations","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/assignments/{id}":{"get":{"summary":"Get a route assignment","tags":["Transportation"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"routeId":{"type":"string","format":"uuid"},"routeNumber":{"type":"string"},"routeName":{"type":"string"},"stopId":{"type":"string","format":"uuid"},"stopSequence":{"type":"integer"},"stopAddress":{"type":"string"},"stopScheduledTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date","nullable":true},"isSpecialEd":{"type":"boolean"},"accommodations":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","routeId","stopId","direction","effectiveFrom","effectiveTo","isSpecialEd","accommodations","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/assignments/{id}/end":{"post":{"summary":"End an assignment (emits StudentUnassignedFromRoute)","tags":["Transportation"],"description":"Stamps `effectiveTo` so the student no longer appears on the active manifest. Historical data stays on file. Defaults to today if `endedOn` is omitted.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"endedOn":{"type":"string","format":"date"},"reason":{"type":"string","maxLength":500}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"routeId":{"type":"string","format":"uuid"},"routeNumber":{"type":"string"},"routeName":{"type":"string"},"stopId":{"type":"string","format":"uuid"},"stopSequence":{"type":"integer"},"stopAddress":{"type":"string"},"stopScheduledTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date","nullable":true},"isSpecialEd":{"type":"boolean"},"accommodations":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","routeId","stopId","direction","effectiveFrom","effectiveTo","isSpecialEd","accommodations","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/alternate-pickups":{"get":{"summary":"List alternate-pickup requests","tags":["Transportation"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"string","enum":["pending","approved","denied"]},"in":"query","name":"status","required":false},{"schema":{"type":"boolean","default":false},"in":"query","name":"pendingOnly","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"activeOn","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"},"pickupAddress":{"type":"string"},"reason":{"type":"string"},"authorizedByGuardianId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","approved","denied"]},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","effectiveFrom","effectiveTo","pickupAddress","reason","authorizedByGuardianId","status","approvedByUserId","approvedAt","denyReason","notes","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Request an alternate pickup (emits AlternatePickupRequested)","tags":["Transportation"],"description":"Opens a request in `pending` status. A district user reviews via /approve or /deny. Requests cannot overlap an existing pending/approved window for the same student.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"},"pickupAddress":{"type":"string","minLength":3,"maxLength":500},"reason":{"type":"string","minLength":3,"maxLength":500},"authorizedByGuardianId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":2000}},"required":["studentId","effectiveFrom","effectiveTo","pickupAddress","reason"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"},"pickupAddress":{"type":"string"},"reason":{"type":"string"},"authorizedByGuardianId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","approved","denied"]},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","effectiveFrom","effectiveTo","pickupAddress","reason","authorizedByGuardianId","status","approvedByUserId","approvedAt","denyReason","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/alternate-pickups/{id}":{"get":{"summary":"Get an alternate-pickup request","tags":["Transportation"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"},"pickupAddress":{"type":"string"},"reason":{"type":"string"},"authorizedByGuardianId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","approved","denied"]},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","effectiveFrom","effectiveTo","pickupAddress","reason","authorizedByGuardianId","status","approvedByUserId","approvedAt","denyReason","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/alternate-pickups/{id}/approve":{"post":{"summary":"Approve an alternate-pickup request (emits AlternatePickupApproved)","tags":["Transportation"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","maxLength":2000}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"},"pickupAddress":{"type":"string"},"reason":{"type":"string"},"authorizedByGuardianId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","approved","denied"]},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","effectiveFrom","effectiveTo","pickupAddress","reason","authorizedByGuardianId","status","approvedByUserId","approvedAt","denyReason","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/alternate-pickups/{id}/deny":{"post":{"summary":"Deny an alternate-pickup request (emits AlternatePickupDenied)","tags":["Transportation"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"},"pickupAddress":{"type":"string"},"reason":{"type":"string"},"authorizedByGuardianId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","approved","denied"]},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","effectiveFrom","effectiveTo","pickupAddress","reason","authorizedByGuardianId","status","approvedByUserId","approvedAt","denyReason","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/field-trips":{"get":{"summary":"List field trips","tags":["Transportation"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","enum":["planned","confirmed","completed","cancelled"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"tripDate":{"type":"string","format":"date"},"destination":{"type":"string"},"departureTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"returnTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"busNumber":{"type":"string","nullable":true},"chaperones":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"phone":{"type":"string","maxLength":30},"personId":{"type":"string","format":"uuid"}},"required":["name"],"additionalProperties":false}},"status":{"type":"string","enum":["planned","confirmed","completed","cancelled"]},"notes":{"type":"string","nullable":true},"rosterCount":{"type":"integer"},"boardedCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","schoolId","tripDate","destination","departureTime","returnTime","busNumber","chaperones","status","notes","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Schedule a field trip (emits FieldTripScheduled)","tags":["Transportation"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolId":{"type":"string","format":"uuid"},"tripDate":{"type":"string","format":"date"},"destination":{"type":"string","minLength":3,"maxLength":500},"departureTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"returnTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"busNumber":{"type":"string","maxLength":30},"chaperones":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"phone":{"type":"string","maxLength":30},"personId":{"type":"string","format":"uuid"}},"required":["name"],"additionalProperties":false},"default":[]},"notes":{"type":"string","maxLength":2000}},"required":["tripDate","destination","departureTime","returnTime"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"tripDate":{"type":"string","format":"date"},"destination":{"type":"string"},"departureTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"returnTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"busNumber":{"type":"string","nullable":true},"chaperones":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"phone":{"type":"string","maxLength":30},"personId":{"type":"string","format":"uuid"}},"required":["name"],"additionalProperties":false}},"status":{"type":"string","enum":["planned","confirmed","completed","cancelled"]},"notes":{"type":"string","nullable":true},"rosterCount":{"type":"integer"},"boardedCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"roster":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fieldTripId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"permissionSlipOn":{"type":"string","format":"date","nullable":true},"boarded":{"type":"boolean"},"boardedAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","fieldTripId","studentPersonId","permissionSlipOn","boarded","boardedAt","notes"],"additionalProperties":false}}},"required":["id","schoolId","tripDate","destination","departureTime","returnTime","busNumber","chaperones","status","notes","createdAt","roster"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/field-trips/{id}":{"get":{"summary":"Get a field trip with its roster","tags":["Transportation"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"tripDate":{"type":"string","format":"date"},"destination":{"type":"string"},"departureTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"returnTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"busNumber":{"type":"string","nullable":true},"chaperones":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"phone":{"type":"string","maxLength":30},"personId":{"type":"string","format":"uuid"}},"required":["name"],"additionalProperties":false}},"status":{"type":"string","enum":["planned","confirmed","completed","cancelled"]},"notes":{"type":"string","nullable":true},"rosterCount":{"type":"integer"},"boardedCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"roster":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fieldTripId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"permissionSlipOn":{"type":"string","format":"date","nullable":true},"boarded":{"type":"boolean"},"boardedAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","fieldTripId","studentPersonId","permissionSlipOn","boarded","boardedAt","notes"],"additionalProperties":false}}},"required":["id","schoolId","tripDate","destination","departureTime","returnTime","busNumber","chaperones","status","notes","createdAt","roster"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Edit a field trip","tags":["Transportation"],"description":"Status transitions emit FieldTripStatusChanged. Other edits are logged as regular updates.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"destination":{"type":"string","minLength":3,"maxLength":500},"tripDate":{"type":"string","format":"date"},"departureTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"returnTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"busNumber":{"type":"string","maxLength":30,"nullable":true},"chaperones":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"phone":{"type":"string","maxLength":30},"personId":{"type":"string","format":"uuid"}},"required":["name"],"additionalProperties":false}},"status":{"type":"string","enum":["planned","confirmed","completed","cancelled"]},"notes":{"type":"string","maxLength":2000,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"tripDate":{"type":"string","format":"date"},"destination":{"type":"string"},"departureTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"returnTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"busNumber":{"type":"string","nullable":true},"chaperones":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"phone":{"type":"string","maxLength":30},"personId":{"type":"string","format":"uuid"}},"required":["name"],"additionalProperties":false}},"status":{"type":"string","enum":["planned","confirmed","completed","cancelled"]},"notes":{"type":"string","nullable":true},"rosterCount":{"type":"integer"},"boardedCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"roster":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fieldTripId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"permissionSlipOn":{"type":"string","format":"date","nullable":true},"boarded":{"type":"boolean"},"boardedAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","fieldTripId","studentPersonId","permissionSlipOn","boarded","boardedAt","notes"],"additionalProperties":false}}},"required":["id","schoolId","tripDate","destination","departureTime","returnTime","busNumber","chaperones","status","notes","createdAt","roster"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/field-trips/{id}/roster":{"patch":{"summary":"Add or remove students from the field-trip roster","tags":["Transportation"],"description":"Emits FieldTripRosterUpdated when any students were added or removed. Duplicates in `add` are silently ignored (the unique constraint covers it).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"add":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"remove":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"tripDate":{"type":"string","format":"date"},"destination":{"type":"string"},"departureTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"returnTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"busNumber":{"type":"string","nullable":true},"chaperones":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"phone":{"type":"string","maxLength":30},"personId":{"type":"string","format":"uuid"}},"required":["name"],"additionalProperties":false}},"status":{"type":"string","enum":["planned","confirmed","completed","cancelled"]},"notes":{"type":"string","nullable":true},"rosterCount":{"type":"integer"},"boardedCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"roster":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fieldTripId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"permissionSlipOn":{"type":"string","format":"date","nullable":true},"boarded":{"type":"boolean"},"boardedAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","fieldTripId","studentPersonId","permissionSlipOn","boarded","boardedAt","notes"],"additionalProperties":false}}},"required":["id","schoolId","tripDate","destination","departureTime","returnTime","busNumber","chaperones","status","notes","createdAt","roster"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transportation/field-trips/{id}/roster/{rosterId}/board":{"post":{"summary":"Mark a roster row as boarded / not boarded","tags":["Transportation"],"description":"Used at bus-loading time to tick off each student. Does not emit a separate event — boarding counts roll up on the trip read.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"boarded":{"type":"boolean"}},"required":["boarded"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"rosterId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"tripDate":{"type":"string","format":"date"},"destination":{"type":"string"},"departureTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"returnTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"busNumber":{"type":"string","nullable":true},"chaperones":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"phone":{"type":"string","maxLength":30},"personId":{"type":"string","format":"uuid"}},"required":["name"],"additionalProperties":false}},"status":{"type":"string","enum":["planned","confirmed","completed","cancelled"]},"notes":{"type":"string","nullable":true},"rosterCount":{"type":"integer"},"boardedCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"roster":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fieldTripId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"permissionSlipOn":{"type":"string","format":"date","nullable":true},"boarded":{"type":"boolean"},"boardedAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id","fieldTripId","studentPersonId","permissionSlipOn","boarded","boardedAt","notes"],"additionalProperties":false}}},"required":["id","schoolId","tripDate","destination","departureTime","returnTime","busNumber","chaperones","status","notes","createdAt","roster"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/students/{id}/transportation":{"get":{"summary":"A guardianed student's bus assignment + any alternate pickups","tags":["Parent Portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"routeId":{"type":"string","format":"uuid"},"routeNumber":{"type":"string"},"routeName":{"type":"string"},"stopId":{"type":"string","format":"uuid"},"stopSequence":{"type":"integer"},"stopAddress":{"type":"string"},"stopScheduledTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date","nullable":true},"isSpecialEd":{"type":"boolean"},"accommodations":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","routeId","stopId","direction","effectiveFrom","effectiveTo","isSpecialEd","accommodations","notes","createdAt"],"additionalProperties":false}},"alternatePickups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"},"pickupAddress":{"type":"string"},"reason":{"type":"string"},"authorizedByGuardianId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","approved","denied"]},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","effectiveFrom","effectiveTo","pickupAddress","reason","authorizedByGuardianId","status","approvedByUserId","approvedAt","denyReason","notes","createdAt"],"additionalProperties":false}}},"required":["assignments","alternatePickups"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/student/me/transportation":{"get":{"summary":"The signed-in student's bus assignment + any alternate pickups","tags":["Student Portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"routeId":{"type":"string","format":"uuid"},"routeNumber":{"type":"string"},"routeName":{"type":"string"},"stopId":{"type":"string","format":"uuid"},"stopSequence":{"type":"integer"},"stopAddress":{"type":"string"},"stopScheduledTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"direction":{"type":"string","enum":["am_pickup","pm_dropoff","both"]},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date","nullable":true},"isSpecialEd":{"type":"boolean"},"accommodations":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","routeId","stopId","direction","effectiveFrom","effectiveTo","isSpecialEd","accommodations","notes","createdAt"],"additionalProperties":false}},"alternatePickups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"},"pickupAddress":{"type":"string"},"reason":{"type":"string"},"authorizedByGuardianId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","approved","denied"]},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","effectiveFrom","effectiveTo","pickupAddress","reason","authorizedByGuardianId","status","approvedByUserId","approvedAt","denyReason","notes","createdAt"],"additionalProperties":false}}},"required":["assignments","alternatePickups"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/students/{id}/alternate-pickups":{"post":{"summary":"Guardian opens an alternate-pickup request (emits AlternatePickupRequested)","tags":["Parent Portal"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"},"pickupAddress":{"type":"string","minLength":3,"maxLength":500},"reason":{"type":"string","minLength":3,"maxLength":500},"authorizedByGuardianId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":2000}},"required":["effectiveFrom","effectiveTo","pickupAddress","reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"},"pickupAddress":{"type":"string"},"reason":{"type":"string"},"authorizedByGuardianId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","approved","denied"]},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","effectiveFrom","effectiveTo","pickupAddress","reason","authorizedByGuardianId","status","approvedByUserId","approvedAt","denyReason","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/applications":{"get":{"summary":"List meal-benefits applications","tags":["Food Service"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["submitted","approved","denied","appealed","withdrawn"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"applicantPersonId","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"applicantPersonId":{"type":"string","format":"uuid"},"applicantName":{"type":"string"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"submittedAt":{"type":"string","format":"date-time"},"signatureOn":{"type":"string","format":"date","nullable":true},"householdSize":{"type":"integer"},"householdIncomeCents":{"type":"integer"},"incomeFrequency":{"type":"string","enum":["weekly","biweekly","semimonthly","monthly","annual"]},"annualizedIncomeCents":{"type":"integer"},"eligibilityBasis":{"type":"string","enum":["income","application","snap","tanf","foster","homeless","migrant","head_start","direct_cert","cep","extended"]},"basisCaseNumber":{"type":"string","nullable":true},"status":{"type":"string","enum":["submitted","approved","denied","appealed","withdrawn"]},"eligibilityCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"reviewedByUserId":{"type":"string","nullable":true},"reviewedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","applicantPersonId","schoolYearId","submittedAt","signatureOn","householdSize","householdIncomeCents","incomeFrequency","annualizedIncomeCents","eligibilityBasis","basisCaseNumber","status","eligibilityCategory","reviewedByUserId","reviewedAt","denyReason","notes","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Submit a meal-benefits application (emits MealApplicationSubmitted)","tags":["Food Service"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"applicantPersonId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"householdSize":{"type":"integer","minimum":1,"maximum":30},"householdIncomeCents":{"type":"integer","minimum":0},"incomeFrequency":{"type":"string","enum":["weekly","biweekly","semimonthly","monthly","annual"]},"eligibilityBasis":{"type":"string","enum":["income","application","snap","tanf","foster","homeless","migrant","head_start","direct_cert","cep","extended"],"default":"income"},"basisCaseNumber":{"type":"string","maxLength":50},"signatureOn":{"type":"string","format":"date"},"members":{"type":"array","items":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"fullName":{"type":"string","minLength":1,"maxLength":200},"relationship":{"type":"string","maxLength":50},"isStudent":{"type":"boolean","default":false},"incomeCents":{"type":"integer","minimum":0,"default":0}},"required":["fullName"],"additionalProperties":false},"minItems":1,"maxItems":30},"notes":{"type":"string","maxLength":2000}},"required":["applicantPersonId","householdSize","householdIncomeCents","incomeFrequency","members"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"applicantPersonId":{"type":"string","format":"uuid"},"applicantName":{"type":"string"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"submittedAt":{"type":"string","format":"date-time"},"signatureOn":{"type":"string","format":"date","nullable":true},"householdSize":{"type":"integer"},"householdIncomeCents":{"type":"integer"},"incomeFrequency":{"type":"string","enum":["weekly","biweekly","semimonthly","monthly","annual"]},"annualizedIncomeCents":{"type":"integer"},"eligibilityBasis":{"type":"string","enum":["income","application","snap","tanf","foster","homeless","migrant","head_start","direct_cert","cep","extended"]},"basisCaseNumber":{"type":"string","nullable":true},"status":{"type":"string","enum":["submitted","approved","denied","appealed","withdrawn"]},"eligibilityCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"reviewedByUserId":{"type":"string","nullable":true},"reviewedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid","nullable":true},"fullName":{"type":"string"},"relationship":{"type":"string","nullable":true},"isStudent":{"type":"boolean"},"incomeCents":{"type":"integer"}},"required":["id","applicationId","studentPersonId","fullName","relationship","isStudent","incomeCents"],"additionalProperties":false}}},"required":["id","applicantPersonId","schoolYearId","submittedAt","signatureOn","householdSize","householdIncomeCents","incomeFrequency","annualizedIncomeCents","eligibilityBasis","basisCaseNumber","status","eligibilityCategory","reviewedByUserId","reviewedAt","denyReason","notes","createdAt","updatedAt","members"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/applications/{id}":{"get":{"summary":"Get a meal-benefits application with its members","tags":["Food Service"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"applicantPersonId":{"type":"string","format":"uuid"},"applicantName":{"type":"string"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"submittedAt":{"type":"string","format":"date-time"},"signatureOn":{"type":"string","format":"date","nullable":true},"householdSize":{"type":"integer"},"householdIncomeCents":{"type":"integer"},"incomeFrequency":{"type":"string","enum":["weekly","biweekly","semimonthly","monthly","annual"]},"annualizedIncomeCents":{"type":"integer"},"eligibilityBasis":{"type":"string","enum":["income","application","snap","tanf","foster","homeless","migrant","head_start","direct_cert","cep","extended"]},"basisCaseNumber":{"type":"string","nullable":true},"status":{"type":"string","enum":["submitted","approved","denied","appealed","withdrawn"]},"eligibilityCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"reviewedByUserId":{"type":"string","nullable":true},"reviewedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid","nullable":true},"fullName":{"type":"string"},"relationship":{"type":"string","nullable":true},"isStudent":{"type":"boolean"},"incomeCents":{"type":"integer"}},"required":["id","applicationId","studentPersonId","fullName","relationship","isStudent","incomeCents"],"additionalProperties":false}}},"required":["id","applicantPersonId","schoolYearId","submittedAt","signatureOn","householdSize","householdIncomeCents","incomeFrequency","annualizedIncomeCents","eligibilityBasis","basisCaseNumber","status","eligibilityCategory","reviewedByUserId","reviewedAt","denyReason","notes","createdAt","updatedAt","members"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/applications/{id}/approve":{"post":{"summary":"Approve an application and stamp eligibility for covered students","tags":["Food Service"],"description":"Derives the NSLP category from the household income (or honors a categorical basis). Writes a MealEligibility row and a MealAccount for every student member. Emits MealApplicationApproved + MealEligibilitySet per student.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"overrideCategory":{"type":"string","enum":["free","reduced","paid"]},"effectiveFrom":{"type":"string","format":"date"},"notes":{"type":"string","maxLength":2000}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"applicantPersonId":{"type":"string","format":"uuid"},"applicantName":{"type":"string"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"submittedAt":{"type":"string","format":"date-time"},"signatureOn":{"type":"string","format":"date","nullable":true},"householdSize":{"type":"integer"},"householdIncomeCents":{"type":"integer"},"incomeFrequency":{"type":"string","enum":["weekly","biweekly","semimonthly","monthly","annual"]},"annualizedIncomeCents":{"type":"integer"},"eligibilityBasis":{"type":"string","enum":["income","application","snap","tanf","foster","homeless","migrant","head_start","direct_cert","cep","extended"]},"basisCaseNumber":{"type":"string","nullable":true},"status":{"type":"string","enum":["submitted","approved","denied","appealed","withdrawn"]},"eligibilityCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"reviewedByUserId":{"type":"string","nullable":true},"reviewedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid","nullable":true},"fullName":{"type":"string"},"relationship":{"type":"string","nullable":true},"isStudent":{"type":"boolean"},"incomeCents":{"type":"integer"}},"required":["id","applicationId","studentPersonId","fullName","relationship","isStudent","incomeCents"],"additionalProperties":false}}},"required":["id","applicantPersonId","schoolYearId","submittedAt","signatureOn","householdSize","householdIncomeCents","incomeFrequency","annualizedIncomeCents","eligibilityBasis","basisCaseNumber","status","eligibilityCategory","reviewedByUserId","reviewedAt","denyReason","notes","createdAt","updatedAt","members"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/applications/{id}/deny":{"post":{"summary":"Deny an application (emits MealApplicationDenied)","tags":["Food Service"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"applicantPersonId":{"type":"string","format":"uuid"},"applicantName":{"type":"string"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"submittedAt":{"type":"string","format":"date-time"},"signatureOn":{"type":"string","format":"date","nullable":true},"householdSize":{"type":"integer"},"householdIncomeCents":{"type":"integer"},"incomeFrequency":{"type":"string","enum":["weekly","biweekly","semimonthly","monthly","annual"]},"annualizedIncomeCents":{"type":"integer"},"eligibilityBasis":{"type":"string","enum":["income","application","snap","tanf","foster","homeless","migrant","head_start","direct_cert","cep","extended"]},"basisCaseNumber":{"type":"string","nullable":true},"status":{"type":"string","enum":["submitted","approved","denied","appealed","withdrawn"]},"eligibilityCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"reviewedByUserId":{"type":"string","nullable":true},"reviewedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid","nullable":true},"fullName":{"type":"string"},"relationship":{"type":"string","nullable":true},"isStudent":{"type":"boolean"},"incomeCents":{"type":"integer"}},"required":["id","applicationId","studentPersonId","fullName","relationship","isStudent","incomeCents"],"additionalProperties":false}}},"required":["id","applicantPersonId","schoolYearId","submittedAt","signatureOn","householdSize","householdIncomeCents","incomeFrequency","annualizedIncomeCents","eligibilityBasis","basisCaseNumber","status","eligibilityCategory","reviewedByUserId","reviewedAt","denyReason","notes","createdAt","updatedAt","members"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/eligibility":{"get":{"summary":"List per-student meal eligibility records","tags":["Food Service"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"string","enum":["free","reduced","paid"]},"in":"query","name":"category","required":false},{"schema":{"type":"string","enum":["income","application","snap","tanf","foster","homeless","migrant","head_start","direct_cert","cep","extended"]},"in":"query","name":"basis","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"activeOn","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"category":{"type":"string","enum":["free","reduced","paid"]},"basis":{"type":"string","enum":["income","application","snap","tanf","foster","homeless","migrant","head_start","direct_cert","cep","extended"]},"applicationId":{"type":"string","format":"uuid","nullable":true},"directCertMatchedOn":{"type":"string","format":"date","nullable":true},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","schoolYearId","category","basis","applicationId","directCertMatchedOn","effectiveFrom","effectiveTo","notes","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Write a per-student eligibility record (emits MealEligibilitySet)","tags":["Food Service"],"description":"Used for direct-certification matches, CEP-district bulk writes, and manual corrections. Open records for the student in the same window are ended at effectiveFrom. Ensures a meal account exists.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"category":{"type":"string","enum":["free","reduced","paid"]},"basis":{"type":"string","enum":["income","application","snap","tanf","foster","homeless","migrant","head_start","direct_cert","cep","extended"]},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"},"schoolYearId":{"type":"string","format":"uuid"},"directCertMatchedOn":{"type":"string","format":"date"},"notes":{"type":"string","maxLength":500}},"required":["studentId","category","basis","effectiveFrom"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"category":{"type":"string","enum":["free","reduced","paid"]},"basis":{"type":"string","enum":["income","application","snap","tanf","foster","homeless","migrant","head_start","direct_cert","cep","extended"]},"applicationId":{"type":"string","format":"uuid","nullable":true},"directCertMatchedOn":{"type":"string","format":"date","nullable":true},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","schoolYearId","category","basis","applicationId","directCertMatchedOn","effectiveFrom","effectiveTo","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/eligibility/summary":{"get":{"summary":"Eligibility category distribution + ISEP","tags":["Food Service"],"description":"Counts active students in each NSLP category (free / reduced / paid) and the Identified Student Percentage (ISEP). ISEP drives whether the district can apply for Community Eligibility Provision (CEP).","parameters":[{"schema":{"type":"string","format":"date"},"in":"query","name":"activeOn","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"free":{"type":"integer"},"reduced":{"type":"integer"},"paid":{"type":"integer"},"total":{"type":"integer"},"isep":{"type":"number"}},"required":["free","reduced","paid","total","isep"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/eligibility/{id}/end":{"post":{"summary":"End an eligibility window (emits MealEligibilityEnded)","tags":["Food Service"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"endedOn":{"type":"string","format":"date"},"reason":{"type":"string","maxLength":500}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"category":{"type":"string","enum":["free","reduced","paid"]},"basis":{"type":"string","enum":["income","application","snap","tanf","foster","homeless","migrant","head_start","direct_cert","cep","extended"]},"applicationId":{"type":"string","format":"uuid","nullable":true},"directCertMatchedOn":{"type":"string","format":"date","nullable":true},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","schoolYearId","category","basis","applicationId","directCertMatchedOn","effectiveFrom","effectiveTo","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/accounts":{"get":{"summary":"List student meal accounts","tags":["Food Service"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["active","closed","frozen"]},"in":"query","name":"status","required":false},{"schema":{"type":"boolean","default":false},"in":"query","name":"belowThreshold","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"balanceCents":{"type":"integer"},"status":{"type":"string","enum":["active","closed","frozen"]},"lowBalanceThresholdCents":{"type":"integer"},"autoReload":{"type":"boolean"},"autoReloadAmountCents":{"type":"integer"},"guardianPaysPersonId":{"type":"string","format":"uuid","nullable":true},"currentCategory":{"type":"string","enum":["free","reduced","paid"]},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","balanceCents","status","lowBalanceThresholdCents","autoReload","autoReloadAmountCents","guardianPaysPersonId","notes","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create or adopt a student meal account","tags":["Food Service"],"description":"Idempotent: if the student already has an account, its settings are updated with any provided fields.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"lowBalanceThresholdCents":{"type":"integer","minimum":0,"default":500},"autoReload":{"type":"boolean","default":false},"autoReloadAmountCents":{"type":"integer","minimum":0,"default":0},"guardianPaysPersonId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":500}},"required":["studentId"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"balanceCents":{"type":"integer"},"status":{"type":"string","enum":["active","closed","frozen"]},"lowBalanceThresholdCents":{"type":"integer"},"autoReload":{"type":"boolean"},"autoReloadAmountCents":{"type":"integer"},"guardianPaysPersonId":{"type":"string","format":"uuid","nullable":true},"currentCategory":{"type":"string","enum":["free","reduced","paid"]},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","balanceCents","status","lowBalanceThresholdCents","autoReload","autoReloadAmountCents","guardianPaysPersonId","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/accounts/{id}":{"get":{"summary":"Get a student meal account","tags":["Food Service"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"balanceCents":{"type":"integer"},"status":{"type":"string","enum":["active","closed","frozen"]},"lowBalanceThresholdCents":{"type":"integer"},"autoReload":{"type":"boolean"},"autoReloadAmountCents":{"type":"integer"},"guardianPaysPersonId":{"type":"string","format":"uuid","nullable":true},"currentCategory":{"type":"string","enum":["free","reduced","paid"]},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","balanceCents","status","lowBalanceThresholdCents","autoReload","autoReloadAmountCents","guardianPaysPersonId","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update meal-account settings","tags":["Food Service"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","closed","frozen"]},"lowBalanceThresholdCents":{"type":"integer","minimum":0},"autoReload":{"type":"boolean"},"autoReloadAmountCents":{"type":"integer","minimum":0},"guardianPaysPersonId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","maxLength":500,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"balanceCents":{"type":"integer"},"status":{"type":"string","enum":["active","closed","frozen"]},"lowBalanceThresholdCents":{"type":"integer"},"autoReload":{"type":"boolean"},"autoReloadAmountCents":{"type":"integer"},"guardianPaysPersonId":{"type":"string","format":"uuid","nullable":true},"currentCategory":{"type":"string","enum":["free","reduced","paid"]},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","balanceCents","status","lowBalanceThresholdCents","autoReload","autoReloadAmountCents","guardianPaysPersonId","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/accounts/{id}/fund":{"post":{"summary":"Add funds to a meal account (emits MealAccountFunded)","tags":["Food Service"],"description":"Records the payment, bumps the balance, and creates a payment transaction. Does NOT run a real payment — integrate a processor at the route boundary and then call this to finalize.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amountCents":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":1000000},"paymentMethod":{"type":"string","enum":["online","cash","check","adjustment"],"default":"online"},"referenceId":{"type":"string","maxLength":50},"notes":{"type":"string","maxLength":500}},"required":["amountCents"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"transactionType":{"type":"string","enum":["purchase","payment","refund","adjustment"]},"amountCents":{"type":"integer"},"servedOn":{"type":"string","format":"date"},"servedAt":{"type":"string","format":"date-time","nullable":true},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"],"nullable":true},"reimbursable":{"type":"boolean"},"eligibilityCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"cashierUserId":{"type":"string","nullable":true},"posTerminalId":{"type":"string","nullable":true},"paymentMethod":{"type":"string","enum":["online","cash","check","adjustment","refund"],"nullable":true},"referenceId":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","accountId","studentPersonId","schoolId","transactionType","amountCents","servedOn","servedAt","mealType","reimbursable","eligibilityCategory","cashierUserId","posTerminalId","paymentMethod","referenceId","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/transactions":{"get":{"summary":"List meal transactions (POS ledger)","tags":["Food Service"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"accountId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","enum":["purchase","payment","refund","adjustment"]},"in":"query","name":"transactionType","required":false},{"schema":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"]},"in":"query","name":"mealType","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"transactionType":{"type":"string","enum":["purchase","payment","refund","adjustment"]},"amountCents":{"type":"integer"},"servedOn":{"type":"string","format":"date"},"servedAt":{"type":"string","format":"date-time","nullable":true},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"],"nullable":true},"reimbursable":{"type":"boolean"},"eligibilityCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"cashierUserId":{"type":"string","nullable":true},"posTerminalId":{"type":"string","nullable":true},"paymentMethod":{"type":"string","enum":["online","cash","check","adjustment","refund"],"nullable":true},"referenceId":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","accountId","studentPersonId","schoolId","transactionType","amountCents","servedOn","servedAt","mealType","reimbursable","eligibilityCategory","cashierUserId","posTerminalId","paymentMethod","referenceId","notes","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/pos/purchase":{"post":{"summary":"Record a POS meal purchase (emits MealPurchased)","tags":["Food Service"],"description":"Looks up the student's current eligibility, charges the correct amount (free = $0, reduced = capped, paid = list price), debits the account, and marks the transaction reimbursable unless meal type is `a_la_carte`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"]},"listPriceCents":{"type":"integer","minimum":0},"servedOn":{"type":"string","format":"date"},"posTerminalId":{"type":"string","maxLength":50},"notes":{"type":"string","maxLength":500}},"required":["studentId","mealType","listPriceCents"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"transactionType":{"type":"string","enum":["purchase","payment","refund","adjustment"]},"amountCents":{"type":"integer"},"servedOn":{"type":"string","format":"date"},"servedAt":{"type":"string","format":"date-time","nullable":true},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"],"nullable":true},"reimbursable":{"type":"boolean"},"eligibilityCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"cashierUserId":{"type":"string","nullable":true},"posTerminalId":{"type":"string","nullable":true},"paymentMethod":{"type":"string","enum":["online","cash","check","adjustment","refund"],"nullable":true},"referenceId":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","accountId","studentPersonId","schoolId","transactionType","amountCents","servedOn","servedAt","mealType","reimbursable","eligibilityCategory","cashierUserId","posTerminalId","paymentMethod","referenceId","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/pos/transactions/{id}/refund":{"post":{"summary":"Refund a prior POS purchase (emits MealRefunded)","tags":["Food Service"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"transactionType":{"type":"string","enum":["purchase","payment","refund","adjustment"]},"amountCents":{"type":"integer"},"servedOn":{"type":"string","format":"date"},"servedAt":{"type":"string","format":"date-time","nullable":true},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"],"nullable":true},"reimbursable":{"type":"boolean"},"eligibilityCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"cashierUserId":{"type":"string","nullable":true},"posTerminalId":{"type":"string","nullable":true},"paymentMethod":{"type":"string","enum":["online","cash","check","adjustment","refund"],"nullable":true},"referenceId":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","accountId","studentPersonId","schoolId","transactionType","amountCents","servedOn","servedAt","mealType","reimbursable","eligibilityCategory","cashierUserId","posTerminalId","paymentMethod","referenceId","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/service-days":{"get":{"summary":"List daily reimbursement claim rollups","tags":["Food Service"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false},{"schema":{"type":"string","enum":["open","closed","claimed"]},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"serviceDate":{"type":"string","format":"date"},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"]},"freeCount":{"type":"integer"},"reducedCount":{"type":"integer"},"paidCount":{"type":"integer"},"adultCount":{"type":"integer"},"totalReimbursable":{"type":"integer"},"status":{"type":"string","enum":["open","closed","claimed"]},"closedByUserId":{"type":"string","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","schoolId","serviceDate","mealType","freeCount","reducedCount","paidCount","adultCount","totalReimbursable","status","closedByUserId","closedAt","notes","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/service-days/close":{"post":{"summary":"Close a day's counts for reimbursement (emits MealServiceDayClosed)","tags":["Food Service"],"description":"Recomputes counts from the ledger, then flips the status to `closed`. Re-runs are safe while status is `open`; once `claimed`, use an audit event to reopen.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolId":{"type":"string","format":"uuid"},"serviceDate":{"type":"string","format":"date"},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"]},"notes":{"type":"string","maxLength":500}},"required":["schoolId","serviceDate","mealType"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"serviceDate":{"type":"string","format":"date"},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"]},"freeCount":{"type":"integer"},"reducedCount":{"type":"integer"},"paidCount":{"type":"integer"},"adultCount":{"type":"integer"},"totalReimbursable":{"type":"integer"},"status":{"type":"string","enum":["open","closed","claimed"]},"closedByUserId":{"type":"string","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","schoolId","serviceDate","mealType","freeCount","reducedCount","paidCount","adultCount","totalReimbursable","status","closedByUserId","closedAt","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/reports/daily-counts":{"get":{"summary":"Daily reimbursable-counts report across a date range","tags":["Food Service"],"description":"The basis for the state claim file. One row per school/date/meal-type. Results include open days so the director can see running totals.","parameters":[{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":true},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":true},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"]},"in":"query","name":"mealType","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"serviceDate":{"type":"string","format":"date"},"schoolId":{"type":"string","format":"uuid"},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"]},"freeCount":{"type":"integer"},"reducedCount":{"type":"integer"},"paidCount":{"type":"integer"},"totalReimbursable":{"type":"integer"},"status":{"type":"string","enum":["open","closed","claimed"]}},"required":["serviceDate","schoolId","mealType","freeCount","reducedCount","paidCount","totalReimbursable","status"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/students/{id}/meal-service":{"get":{"summary":"Guardianed student's meal account + eligibility + recent activity","tags":["Parent Portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"account":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"balanceCents":{"type":"integer"},"status":{"type":"string","enum":["active","closed","frozen"]},"lowBalanceThresholdCents":{"type":"integer"},"autoReload":{"type":"boolean"},"autoReloadAmountCents":{"type":"integer"},"guardianPaysPersonId":{"type":"string","format":"uuid","nullable":true},"currentCategory":{"type":"string","enum":["free","reduced","paid"]},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","balanceCents","status","lowBalanceThresholdCents","autoReload","autoReloadAmountCents","guardianPaysPersonId","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"currentCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"recentTransactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"transactionType":{"type":"string","enum":["purchase","payment","refund","adjustment"]},"amountCents":{"type":"integer"},"servedOn":{"type":"string","format":"date"},"servedAt":{"type":"string","format":"date-time","nullable":true},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"],"nullable":true},"reimbursable":{"type":"boolean"},"eligibilityCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"cashierUserId":{"type":"string","nullable":true},"posTerminalId":{"type":"string","nullable":true},"paymentMethod":{"type":"string","enum":["online","cash","check","adjustment","refund"],"nullable":true},"referenceId":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","accountId","studentPersonId","schoolId","transactionType","amountCents","servedOn","servedAt","mealType","reimbursable","eligibilityCategory","cashierUserId","posTerminalId","paymentMethod","referenceId","notes","createdAt"],"additionalProperties":false}},"pendingApplicationId":{"type":"string","format":"uuid","nullable":true}},"required":["studentPersonId","studentName","account","currentCategory","recentTransactions","pendingApplicationId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/student/me/meal-service":{"get":{"summary":"Signed-in student's meal account + recent activity","tags":["Student Portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"account":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"balanceCents":{"type":"integer"},"status":{"type":"string","enum":["active","closed","frozen"]},"lowBalanceThresholdCents":{"type":"integer"},"autoReload":{"type":"boolean"},"autoReloadAmountCents":{"type":"integer"},"guardianPaysPersonId":{"type":"string","format":"uuid","nullable":true},"currentCategory":{"type":"string","enum":["free","reduced","paid"]},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","balanceCents","status","lowBalanceThresholdCents","autoReload","autoReloadAmountCents","guardianPaysPersonId","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"currentCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"recentTransactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"transactionType":{"type":"string","enum":["purchase","payment","refund","adjustment"]},"amountCents":{"type":"integer"},"servedOn":{"type":"string","format":"date"},"servedAt":{"type":"string","format":"date-time","nullable":true},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"],"nullable":true},"reimbursable":{"type":"boolean"},"eligibilityCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"cashierUserId":{"type":"string","nullable":true},"posTerminalId":{"type":"string","nullable":true},"paymentMethod":{"type":"string","enum":["online","cash","check","adjustment","refund"],"nullable":true},"referenceId":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","accountId","studentPersonId","schoolId","transactionType","amountCents","servedOn","servedAt","mealType","reimbursable","eligibilityCategory","cashierUserId","posTerminalId","paymentMethod","referenceId","notes","createdAt"],"additionalProperties":false}},"pendingApplicationId":{"type":"string","format":"uuid","nullable":true}},"required":["studentPersonId","studentName","account","currentCategory","recentTransactions","pendingApplicationId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/students/{id}/meal-service/fund":{"post":{"summary":"Guardian adds funds to a student's meal account (emits MealAccountFunded)","tags":["Parent Portal"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amountCents":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":1000000},"paymentMethod":{"type":"string","enum":["online","cash","check","adjustment"],"default":"online"},"referenceId":{"type":"string","maxLength":50},"notes":{"type":"string","maxLength":500}},"required":["amountCents"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"transactionType":{"type":"string","enum":["purchase","payment","refund","adjustment"]},"amountCents":{"type":"integer"},"servedOn":{"type":"string","format":"date"},"servedAt":{"type":"string","format":"date-time","nullable":true},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"],"nullable":true},"reimbursable":{"type":"boolean"},"eligibilityCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"cashierUserId":{"type":"string","nullable":true},"posTerminalId":{"type":"string","nullable":true},"paymentMethod":{"type":"string","enum":["online","cash","check","adjustment","refund"],"nullable":true},"referenceId":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","accountId","studentPersonId","schoolId","transactionType","amountCents","servedOn","servedAt","mealType","reimbursable","eligibilityCategory","cashierUserId","posTerminalId","paymentMethod","referenceId","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/meal-service/applications":{"post":{"summary":"Submit a household meal-benefits application","tags":["Parent Portal"],"description":"Applicant must be the signed-in guardian. Each student member must be a student this guardian is linked to.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"householdSize":{"type":"integer","minimum":1,"maximum":30},"householdIncomeCents":{"type":"integer","minimum":0},"incomeFrequency":{"type":"string","enum":["weekly","biweekly","semimonthly","monthly","annual"]},"eligibilityBasis":{"type":"string","enum":["income","application","snap","tanf","foster","homeless","migrant","head_start","direct_cert","cep","extended"],"default":"income"},"basisCaseNumber":{"type":"string","maxLength":50},"signatureOn":{"type":"string","format":"date"},"members":{"type":"array","items":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"fullName":{"type":"string","minLength":1,"maxLength":200},"relationship":{"type":"string","maxLength":50},"isStudent":{"type":"boolean","default":false},"incomeCents":{"type":"integer","minimum":0,"default":0}},"required":["fullName"],"additionalProperties":false},"minItems":1,"maxItems":30},"notes":{"type":"string","maxLength":2000}},"required":["householdSize","householdIncomeCents","incomeFrequency","members"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"applicantPersonId":{"type":"string","format":"uuid"},"applicantName":{"type":"string"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"submittedAt":{"type":"string","format":"date-time"},"signatureOn":{"type":"string","format":"date","nullable":true},"householdSize":{"type":"integer"},"householdIncomeCents":{"type":"integer"},"incomeFrequency":{"type":"string","enum":["weekly","biweekly","semimonthly","monthly","annual"]},"annualizedIncomeCents":{"type":"integer"},"eligibilityBasis":{"type":"string","enum":["income","application","snap","tanf","foster","homeless","migrant","head_start","direct_cert","cep","extended"]},"basisCaseNumber":{"type":"string","nullable":true},"status":{"type":"string","enum":["submitted","approved","denied","appealed","withdrawn"]},"eligibilityCategory":{"type":"string","enum":["free","reduced","paid"],"nullable":true},"reviewedByUserId":{"type":"string","nullable":true},"reviewedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid","nullable":true},"fullName":{"type":"string"},"relationship":{"type":"string","nullable":true},"isStudent":{"type":"boolean"},"incomeCents":{"type":"integer"}},"required":["id","applicationId","studentPersonId","fullName","relationship","isStudent","incomeCents"],"additionalProperties":false}}},"required":["id","applicantPersonId","schoolYearId","submittedAt","signatureOn","householdSize","householdIncomeCents","incomeFrequency","annualizedIncomeCents","eligibilityBasis","basisCaseNumber","status","eligibilityCategory","reviewedByUserId","reviewedAt","denyReason","notes","createdAt","updatedAt","members"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/direct-cert/imports":{"get":{"summary":"List direct-certification CSV imports","tags":["Food Service – Direct Cert"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["preview","applied","discarded"]},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"filename":{"type":"string"},"importedByUserId":{"type":"string","format":"uuid"},"rowCount":{"type":"integer"},"matchedCount":{"type":"integer"},"unmatchedCount":{"type":"integer"},"status":{"type":"string","enum":["preview","applied","discarded"]},"appliedAt":{"type":"string","format":"date-time","nullable":true},"appliedByUserId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolYearId","filename","importedByUserId","rowCount","matchedCount","unmatchedCount","status","appliedAt","appliedByUserId","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Upload a state direct-cert CSV (returns a preview; not yet applied)","tags":["Food Service – Direct Cert"],"description":"Parse the CSV, match against the enrolled student roster, and persist a `preview` import. No eligibility records are written until you POST to `/:id/apply`. The CSV text is accepted as a JSON string field to avoid a multipart dependency.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"csvData":{"type":"string","minLength":1,"maxLength":2000000},"schoolYearId":{"type":"string","format":"uuid"}},"required":["filename","csvData"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"filename":{"type":"string"},"importedByUserId":{"type":"string","format":"uuid"},"rowCount":{"type":"integer"},"matchedCount":{"type":"integer"},"unmatchedCount":{"type":"integer"},"status":{"type":"string","enum":["preview","applied","discarded"]},"appliedAt":{"type":"string","format":"date-time","nullable":true},"appliedByUserId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"importId":{"type":"string","format":"uuid"},"rowNumber":{"type":"integer"},"stateStudentId":{"type":"string","nullable":true},"lastName":{"type":"string"},"firstName":{"type":"string"},"dateOfBirth":{"type":"string","nullable":true},"program":{"type":"string","enum":["snap","tanf","foster","medicaid","homeless","migrant"]},"matchedStudentId":{"type":"string","format":"uuid","nullable":true},"matchConfidence":{"type":"string","enum":["exact","fuzzy","none"]},"matchReason":{"type":"string","nullable":true},"eligibilityId":{"type":"string","format":"uuid","nullable":true},"overriddenByUserId":{"type":"string","format":"uuid","nullable":true},"overrideAction":{"type":"string","enum":["accept","reject"],"nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","importId","rowNumber","stateStudentId","lastName","firstName","dateOfBirth","program","matchedStudentId","matchConfidence","matchReason","eligibilityId","overriddenByUserId","overrideAction","createdAt","updatedAt"],"additionalProperties":false}},"parseErrors":{"type":"array","items":{"type":"string"}}},"required":["id","districtId","schoolYearId","filename","importedByUserId","rowCount","matchedCount","unmatchedCount","status","appliedAt","appliedByUserId","createdAt","updatedAt","results"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/direct-cert/imports/{id}":{"get":{"summary":"Get a direct-cert import with all per-student result rows","tags":["Food Service – Direct Cert"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"filename":{"type":"string"},"importedByUserId":{"type":"string","format":"uuid"},"rowCount":{"type":"integer"},"matchedCount":{"type":"integer"},"unmatchedCount":{"type":"integer"},"status":{"type":"string","enum":["preview","applied","discarded"]},"appliedAt":{"type":"string","format":"date-time","nullable":true},"appliedByUserId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"importId":{"type":"string","format":"uuid"},"rowNumber":{"type":"integer"},"stateStudentId":{"type":"string","nullable":true},"lastName":{"type":"string"},"firstName":{"type":"string"},"dateOfBirth":{"type":"string","nullable":true},"program":{"type":"string","enum":["snap","tanf","foster","medicaid","homeless","migrant"]},"matchedStudentId":{"type":"string","format":"uuid","nullable":true},"matchConfidence":{"type":"string","enum":["exact","fuzzy","none"]},"matchReason":{"type":"string","nullable":true},"eligibilityId":{"type":"string","format":"uuid","nullable":true},"overriddenByUserId":{"type":"string","format":"uuid","nullable":true},"overrideAction":{"type":"string","enum":["accept","reject"],"nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","importId","rowNumber","stateStudentId","lastName","firstName","dateOfBirth","program","matchedStudentId","matchConfidence","matchReason","eligibilityId","overriddenByUserId","overrideAction","createdAt","updatedAt"],"additionalProperties":false}},"parseErrors":{"type":"array","items":{"type":"string"}}},"required":["id","districtId","schoolYearId","filename","importedByUserId","rowCount","matchedCount","unmatchedCount","status","appliedAt","appliedByUserId","createdAt","updatedAt","results"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/direct-cert/imports/{id}/apply":{"post":{"summary":"Apply a preview import — writes eligibility records for all matched students","tags":["Food Service – Direct Cert"],"description":"Stamps a `MealEligibility` row (basis=direct_cert, category=free) for every matched (or manually accepted) result row, then marks the import as `applied`. This action is irreversible — discard first if you want to reject the import.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"effectiveFrom":{"type":"string","format":"date"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"filename":{"type":"string"},"importedByUserId":{"type":"string","format":"uuid"},"rowCount":{"type":"integer"},"matchedCount":{"type":"integer"},"unmatchedCount":{"type":"integer"},"status":{"type":"string","enum":["preview","applied","discarded"]},"appliedAt":{"type":"string","format":"date-time","nullable":true},"appliedByUserId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"importId":{"type":"string","format":"uuid"},"rowNumber":{"type":"integer"},"stateStudentId":{"type":"string","nullable":true},"lastName":{"type":"string"},"firstName":{"type":"string"},"dateOfBirth":{"type":"string","nullable":true},"program":{"type":"string","enum":["snap","tanf","foster","medicaid","homeless","migrant"]},"matchedStudentId":{"type":"string","format":"uuid","nullable":true},"matchConfidence":{"type":"string","enum":["exact","fuzzy","none"]},"matchReason":{"type":"string","nullable":true},"eligibilityId":{"type":"string","format":"uuid","nullable":true},"overriddenByUserId":{"type":"string","format":"uuid","nullable":true},"overrideAction":{"type":"string","enum":["accept","reject"],"nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","importId","rowNumber","stateStudentId","lastName","firstName","dateOfBirth","program","matchedStudentId","matchConfidence","matchReason","eligibilityId","overriddenByUserId","overrideAction","createdAt","updatedAt"],"additionalProperties":false}},"parseErrors":{"type":"array","items":{"type":"string"}}},"required":["id","districtId","schoolYearId","filename","importedByUserId","rowCount","matchedCount","unmatchedCount","status","appliedAt","appliedByUserId","createdAt","updatedAt","results"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/direct-cert/imports/{id}/discard":{"post":{"summary":"Discard a preview import (no eligibility records written)","tags":["Food Service – Direct Cert"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"filename":{"type":"string"},"importedByUserId":{"type":"string","format":"uuid"},"rowCount":{"type":"integer"},"matchedCount":{"type":"integer"},"unmatchedCount":{"type":"integer"},"status":{"type":"string","enum":["preview","applied","discarded"]},"appliedAt":{"type":"string","format":"date-time","nullable":true},"appliedByUserId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"importId":{"type":"string","format":"uuid"},"rowNumber":{"type":"integer"},"stateStudentId":{"type":"string","nullable":true},"lastName":{"type":"string"},"firstName":{"type":"string"},"dateOfBirth":{"type":"string","nullable":true},"program":{"type":"string","enum":["snap","tanf","foster","medicaid","homeless","migrant"]},"matchedStudentId":{"type":"string","format":"uuid","nullable":true},"matchConfidence":{"type":"string","enum":["exact","fuzzy","none"]},"matchReason":{"type":"string","nullable":true},"eligibilityId":{"type":"string","format":"uuid","nullable":true},"overriddenByUserId":{"type":"string","format":"uuid","nullable":true},"overrideAction":{"type":"string","enum":["accept","reject"],"nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","importId","rowNumber","stateStudentId","lastName","firstName","dateOfBirth","program","matchedStudentId","matchConfidence","matchReason","eligibilityId","overriddenByUserId","overrideAction","createdAt","updatedAt"],"additionalProperties":false}},"parseErrors":{"type":"array","items":{"type":"string"}}},"required":["id","districtId","schoolYearId","filename","importedByUserId","rowCount","matchedCount","unmatchedCount","status","appliedAt","appliedByUserId","createdAt","updatedAt","results"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/direct-cert/imports/{id}/results/{resultId}":{"patch":{"summary":"Manually accept or reject a single match row before applying","tags":["Food Service – Direct Cert"],"description":"Use `action=accept` to link an unmatched row to a specific student. Use `action=reject` to prevent an incorrectly auto-matched row from receiving an eligibility record when the import is applied.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["accept","reject"]},"studentPersonId":{"type":"string","format":"uuid"}},"required":["action"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"resultId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"filename":{"type":"string"},"importedByUserId":{"type":"string","format":"uuid"},"rowCount":{"type":"integer"},"matchedCount":{"type":"integer"},"unmatchedCount":{"type":"integer"},"status":{"type":"string","enum":["preview","applied","discarded"]},"appliedAt":{"type":"string","format":"date-time","nullable":true},"appliedByUserId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"importId":{"type":"string","format":"uuid"},"rowNumber":{"type":"integer"},"stateStudentId":{"type":"string","nullable":true},"lastName":{"type":"string"},"firstName":{"type":"string"},"dateOfBirth":{"type":"string","nullable":true},"program":{"type":"string","enum":["snap","tanf","foster","medicaid","homeless","migrant"]},"matchedStudentId":{"type":"string","format":"uuid","nullable":true},"matchConfidence":{"type":"string","enum":["exact","fuzzy","none"]},"matchReason":{"type":"string","nullable":true},"eligibilityId":{"type":"string","format":"uuid","nullable":true},"overriddenByUserId":{"type":"string","format":"uuid","nullable":true},"overrideAction":{"type":"string","enum":["accept","reject"],"nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","importId","rowNumber","stateStudentId","lastName","firstName","dateOfBirth","program","matchedStudentId","matchConfidence","matchReason","eligibilityId","overriddenByUserId","overrideAction","createdAt","updatedAt"],"additionalProperties":false}},"parseErrors":{"type":"array","items":{"type":"string"}}},"required":["id","districtId","schoolYearId","filename","importedByUserId","rowCount","matchedCount","unmatchedCount","status","appliedAt","appliedByUserId","createdAt","updatedAt","results"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/pos/inbound":{"post":{"summary":"External POS terminal webhook — ingest a transaction for staging","tags":["Food Service – POS Inbound"],"description":"Called by external POS hardware or software on each meal served. The request MUST include an `X-Forge-Signature: sha256=<hex-hmac>` header computed over the raw JSON body using the terminal's shared secret configured in `District.settings.posTerminals[terminalId].secret`. Duplicate payloads (same districtId + terminalId + externalTxnId) are silently accepted and return the existing record — safe for at-least-once delivery.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"terminalId":{"type":"string","minLength":1,"maxLength":100},"externalTxnId":{"type":"string","minLength":1,"maxLength":100},"servedOn":{"type":"string","format":"date"},"amountCents":{"type":"integer","exclusiveMinimum":true,"minimum":0},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"]},"studentExternalId":{"type":"string","maxLength":50},"payload":{"type":"object","additionalProperties":{}}},"required":["terminalId","externalTxnId","servedOn","amountCents","mealType","payload"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"terminalId":{"type":"string"},"externalTxnId":{"type":"string"},"matchedStudentId":{"type":"string","format":"uuid","nullable":true},"matchedAccountId":{"type":"string","format":"uuid","nullable":true},"mealTransactionId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","matched","unmatched","reconciled","ignored"]},"servedOn":{"type":"string","format":"date"},"amountCents":{"type":"integer"},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"]},"receivedAt":{"type":"string","format":"date-time"},"reconciledAt":{"type":"string","format":"date-time","nullable":true},"reconciledByUserId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","terminalId","externalTxnId","matchedStudentId","matchedAccountId","mealTransactionId","status","servedOn","amountCents","mealType","receivedAt","reconciledAt","reconciledByUserId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"get":{"summary":"List external POS inbound transactions (staging)","tags":["Food Service – POS Inbound"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["pending","matched","unmatched","reconciled","ignored"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"terminalId","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"terminalId":{"type":"string"},"externalTxnId":{"type":"string"},"matchedStudentId":{"type":"string","format":"uuid","nullable":true},"matchedAccountId":{"type":"string","format":"uuid","nullable":true},"mealTransactionId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","matched","unmatched","reconciled","ignored"]},"servedOn":{"type":"string","format":"date"},"amountCents":{"type":"integer"},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"]},"receivedAt":{"type":"string","format":"date-time"},"reconciledAt":{"type":"string","format":"date-time","nullable":true},"reconciledByUserId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","terminalId","externalTxnId","matchedStudentId","matchedAccountId","mealTransactionId","status","servedOn","amountCents","mealType","receivedAt","reconciledAt","reconciledByUserId","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/pos/inbound/{id}":{"get":{"summary":"Get a single external POS inbound transaction","tags":["Food Service – POS Inbound"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"terminalId":{"type":"string"},"externalTxnId":{"type":"string"},"matchedStudentId":{"type":"string","format":"uuid","nullable":true},"matchedAccountId":{"type":"string","format":"uuid","nullable":true},"mealTransactionId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","matched","unmatched","reconciled","ignored"]},"servedOn":{"type":"string","format":"date"},"amountCents":{"type":"integer"},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"]},"receivedAt":{"type":"string","format":"date-time"},"reconciledAt":{"type":"string","format":"date-time","nullable":true},"reconciledByUserId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","terminalId","externalTxnId","matchedStudentId","matchedAccountId","mealTransactionId","status","servedOn","amountCents","mealType","receivedAt","reconciledAt","reconciledByUserId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/pos/inbound/{id}/reconcile":{"post":{"summary":"Reconcile a staged POS transaction → writes a canonical MealTransaction","tags":["Food Service – POS Inbound"],"description":"The director confirms the student was present and received the meal. This writes a `MealTransaction` via the same `recordPurchase` path used by the internal cashier POS (eligibility lookup, free/reduced pricing, reimbursable flag, service-day rollup rebuild all apply).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":500}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"terminalId":{"type":"string"},"externalTxnId":{"type":"string"},"matchedStudentId":{"type":"string","format":"uuid","nullable":true},"matchedAccountId":{"type":"string","format":"uuid","nullable":true},"mealTransactionId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","matched","unmatched","reconciled","ignored"]},"servedOn":{"type":"string","format":"date"},"amountCents":{"type":"integer"},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"]},"receivedAt":{"type":"string","format":"date-time"},"reconciledAt":{"type":"string","format":"date-time","nullable":true},"reconciledByUserId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","terminalId","externalTxnId","matchedStudentId","matchedAccountId","mealTransactionId","status","servedOn","amountCents","mealType","receivedAt","reconciledAt","reconciledByUserId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/pos/inbound/{id}/ignore":{"post":{"summary":"Mark a staged POS transaction as ignored (no meal transaction created)","tags":["Food Service – POS Inbound"],"description":"Use when a transaction is a duplicate, test ping, or a non-meal event from the external terminal. Ignored rows stay in the audit log but do not affect counts or reimbursable totals.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"terminalId":{"type":"string"},"externalTxnId":{"type":"string"},"matchedStudentId":{"type":"string","format":"uuid","nullable":true},"matchedAccountId":{"type":"string","format":"uuid","nullable":true},"mealTransactionId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","matched","unmatched","reconciled","ignored"]},"servedOn":{"type":"string","format":"date"},"amountCents":{"type":"integer"},"mealType":{"type":"string","enum":["breakfast","lunch","snack","a_la_carte"]},"receivedAt":{"type":"string","format":"date-time"},"reconciledAt":{"type":"string","format":"date-time","nullable":true},"reconciledByUserId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","terminalId","externalTxnId","matchedStudentId","matchedAccountId","mealTransactionId","status","servedOn","amountCents","mealType","receivedAt","reconciledAt","reconciledByUserId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/meal-service/pos/inbound/reconciliation":{"get":{"summary":"POS inbound reconciliation summary — counts per terminal over a date range","tags":["Food Service – POS Inbound"],"parameters":[{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false},{"schema":{"type":"string"},"in":"query","name":"terminalId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"terminalId":{"type":"string"},"totalPending":{"type":"integer"},"totalMatched":{"type":"integer"},"totalReconciled":{"type":"integer"},"totalIgnored":{"type":"integer"},"totalAmountCents":{"type":"integer"},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}},"required":["from","to"],"additionalProperties":false}},"required":["terminalId","totalPending","totalMatched","totalReconciled","totalIgnored","totalAmountCents","period"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/fees/catalog":{"get":{"summary":"List fee catalog entries","tags":["Fees"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["registration","ap_exam","athletics","field_trip","course","other"]},"in":"query","name":"category","required":false},{"schema":{"type":"boolean"},"in":"query","name":"isActive","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["registration","ap_exam","athletics","field_trip","course","other"]},"amountCents":{"type":"integer"},"isActive":{"type":"boolean"},"isTaxable":{"type":"boolean"},"glAccount":{"type":"string","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","code","name","category","amountCents","isActive","isTaxable","glAccount","schoolYearId","notes","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a fee catalog entry (emits FeeCatalogCreated)","tags":["Fees"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":40},"name":{"type":"string","minLength":1,"maxLength":200},"category":{"type":"string","enum":["registration","ap_exam","athletics","field_trip","course","other"]},"amountCents":{"type":"integer","minimum":0,"maximum":10000000},"isActive":{"type":"boolean","default":true},"isTaxable":{"type":"boolean","default":false},"glAccount":{"type":"string","maxLength":60},"schoolYearId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":500}},"required":["code","name","category","amountCents"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["registration","ap_exam","athletics","field_trip","course","other"]},"amountCents":{"type":"integer"},"isActive":{"type":"boolean"},"isTaxable":{"type":"boolean"},"glAccount":{"type":"string","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","code","name","category","amountCents","isActive","isTaxable","glAccount","schoolYearId","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/fees/catalog/{id}":{"get":{"summary":"Get a fee catalog entry","tags":["Fees"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["registration","ap_exam","athletics","field_trip","course","other"]},"amountCents":{"type":"integer"},"isActive":{"type":"boolean"},"isTaxable":{"type":"boolean"},"glAccount":{"type":"string","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","code","name","category","amountCents","isActive","isTaxable","glAccount","schoolYearId","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a fee catalog entry (emits FeeCatalogUpdated)","tags":["Fees"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"category":{"type":"string","enum":["registration","ap_exam","athletics","field_trip","course","other"]},"amountCents":{"type":"integer","minimum":0,"maximum":10000000},"isActive":{"type":"boolean"},"isTaxable":{"type":"boolean"},"glAccount":{"type":"string","maxLength":60,"nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","maxLength":500,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["registration","ap_exam","athletics","field_trip","course","other"]},"amountCents":{"type":"integer"},"isActive":{"type":"boolean"},"isTaxable":{"type":"boolean"},"glAccount":{"type":"string","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","code","name","category","amountCents","isActive","isTaxable","glAccount","schoolYearId","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Archive a fee catalog entry (soft delete; emits FeeCatalogArchived)","tags":["Fees"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["registration","ap_exam","athletics","field_trip","course","other"]},"amountCents":{"type":"integer"},"isActive":{"type":"boolean"},"isTaxable":{"type":"boolean"},"glAccount":{"type":"string","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","code","name","category","amountCents","isActive","isTaxable","glAccount","schoolYearId","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/fees":{"get":{"summary":"List student fees","tags":["Fees"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"string","enum":["open","partial","paid","void","waived"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["registration","ap_exam","athletics","field_trip","course","other"]},"in":"query","name":"category","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"dueBefore","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"feeCatalogId":{"type":"string","format":"uuid","nullable":true},"feeCatalogCode":{"type":"string","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"description":{"type":"string"},"amountCents":{"type":"integer"},"balanceCents":{"type":"integer"},"paidCents":{"type":"integer"},"status":{"type":"string","enum":["open","partial","paid","void","waived"]},"dueOn":{"type":"string","format":"date","nullable":true},"assessedOn":{"type":"string","format":"date"},"assessedByUserId":{"type":"string","nullable":true},"waivedByUserId":{"type":"string","nullable":true},"waivedAt":{"type":"string","format":"date-time","nullable":true},"waivedReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","feeCatalogId","schoolYearId","code","description","amountCents","balanceCents","status","dueOn","assessedOn","assessedByUserId","waivedByUserId","waivedAt","waivedReason","notes","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Assess a single fee against a student (emits FeeAssessed)","tags":["Fees"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"feeCatalogId":{"type":"string","format":"uuid"},"code":{"type":"string","maxLength":40},"description":{"type":"string","maxLength":300},"amountCents":{"type":"integer","minimum":0,"maximum":10000000},"schoolYearId":{"type":"string","format":"uuid"},"dueOn":{"type":"string","format":"date"},"notes":{"type":"string","maxLength":500}},"required":["studentId"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"feeCatalogId":{"type":"string","format":"uuid","nullable":true},"feeCatalogCode":{"type":"string","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"description":{"type":"string"},"amountCents":{"type":"integer"},"balanceCents":{"type":"integer"},"paidCents":{"type":"integer"},"status":{"type":"string","enum":["open","partial","paid","void","waived"]},"dueOn":{"type":"string","format":"date","nullable":true},"assessedOn":{"type":"string","format":"date"},"assessedByUserId":{"type":"string","nullable":true},"waivedByUserId":{"type":"string","nullable":true},"waivedAt":{"type":"string","format":"date-time","nullable":true},"waivedReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentFeeId":{"type":"string","format":"uuid"},"amountCents":{"type":"integer"},"paymentMethod":{"type":"string","enum":["stripe","school_cash","cash","check","adjustment","refund"]},"processor":{"type":"string","enum":["stripe","manual","school_cash","adjustment"]},"processorIntentId":{"type":"string","nullable":true},"processorChargeId":{"type":"string","nullable":true},"processorStatus":{"type":"string","enum":["succeeded","pending","failed"],"nullable":true},"referenceId":{"type":"string","nullable":true},"refundedFromId":{"type":"string","format":"uuid","nullable":true},"paidByUserId":{"type":"string","nullable":true},"paidAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentFeeId","amountCents","paymentMethod","processor","processorIntentId","processorChargeId","processorStatus","referenceId","refundedFromId","paidByUserId","paidAt","notes","createdAt"],"additionalProperties":false}}},"required":["id","studentPersonId","feeCatalogId","schoolYearId","code","description","amountCents","balanceCents","status","dueOn","assessedOn","assessedByUserId","waivedByUserId","waivedAt","waivedReason","notes","createdAt","updatedAt","payments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/fees/{id}":{"get":{"summary":"Get a student fee with its payments","tags":["Fees"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"feeCatalogId":{"type":"string","format":"uuid","nullable":true},"feeCatalogCode":{"type":"string","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"description":{"type":"string"},"amountCents":{"type":"integer"},"balanceCents":{"type":"integer"},"paidCents":{"type":"integer"},"status":{"type":"string","enum":["open","partial","paid","void","waived"]},"dueOn":{"type":"string","format":"date","nullable":true},"assessedOn":{"type":"string","format":"date"},"assessedByUserId":{"type":"string","nullable":true},"waivedByUserId":{"type":"string","nullable":true},"waivedAt":{"type":"string","format":"date-time","nullable":true},"waivedReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentFeeId":{"type":"string","format":"uuid"},"amountCents":{"type":"integer"},"paymentMethod":{"type":"string","enum":["stripe","school_cash","cash","check","adjustment","refund"]},"processor":{"type":"string","enum":["stripe","manual","school_cash","adjustment"]},"processorIntentId":{"type":"string","nullable":true},"processorChargeId":{"type":"string","nullable":true},"processorStatus":{"type":"string","enum":["succeeded","pending","failed"],"nullable":true},"referenceId":{"type":"string","nullable":true},"refundedFromId":{"type":"string","format":"uuid","nullable":true},"paidByUserId":{"type":"string","nullable":true},"paidAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentFeeId","amountCents","paymentMethod","processor","processorIntentId","processorChargeId","processorStatus","referenceId","refundedFromId","paidByUserId","paidAt","notes","createdAt"],"additionalProperties":false}}},"required":["id","studentPersonId","feeCatalogId","schoolYearId","code","description","amountCents","balanceCents","status","dueOn","assessedOn","assessedByUserId","waivedByUserId","waivedAt","waivedReason","notes","createdAt","updatedAt","payments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/fees/bulk-assess":{"post":{"summary":"Assess a catalog fee against many students (emits one FeeAssessed per student)","tags":["Fees"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"feeCatalogId":{"type":"string","format":"uuid"},"studentIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500},"dueOn":{"type":"string","format":"date"},"schoolYearId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":500}},"required":["feeCatalogId","studentIds"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"feeCatalogId":{"type":"string","format":"uuid","nullable":true},"feeCatalogCode":{"type":"string","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"description":{"type":"string"},"amountCents":{"type":"integer"},"balanceCents":{"type":"integer"},"paidCents":{"type":"integer"},"status":{"type":"string","enum":["open","partial","paid","void","waived"]},"dueOn":{"type":"string","format":"date","nullable":true},"assessedOn":{"type":"string","format":"date"},"assessedByUserId":{"type":"string","nullable":true},"waivedByUserId":{"type":"string","nullable":true},"waivedAt":{"type":"string","format":"date-time","nullable":true},"waivedReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","feeCatalogId","schoolYearId","code","description","amountCents","balanceCents","status","dueOn","assessedOn","assessedByUserId","waivedByUserId","waivedAt","waivedReason","notes","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/fees/{id}/waive":{"post":{"summary":"Waive a student fee (admin forgiveness; emits FeeWaived)","tags":["Fees"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"feeCatalogId":{"type":"string","format":"uuid","nullable":true},"feeCatalogCode":{"type":"string","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"description":{"type":"string"},"amountCents":{"type":"integer"},"balanceCents":{"type":"integer"},"paidCents":{"type":"integer"},"status":{"type":"string","enum":["open","partial","paid","void","waived"]},"dueOn":{"type":"string","format":"date","nullable":true},"assessedOn":{"type":"string","format":"date"},"assessedByUserId":{"type":"string","nullable":true},"waivedByUserId":{"type":"string","nullable":true},"waivedAt":{"type":"string","format":"date-time","nullable":true},"waivedReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentFeeId":{"type":"string","format":"uuid"},"amountCents":{"type":"integer"},"paymentMethod":{"type":"string","enum":["stripe","school_cash","cash","check","adjustment","refund"]},"processor":{"type":"string","enum":["stripe","manual","school_cash","adjustment"]},"processorIntentId":{"type":"string","nullable":true},"processorChargeId":{"type":"string","nullable":true},"processorStatus":{"type":"string","enum":["succeeded","pending","failed"],"nullable":true},"referenceId":{"type":"string","nullable":true},"refundedFromId":{"type":"string","format":"uuid","nullable":true},"paidByUserId":{"type":"string","nullable":true},"paidAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentFeeId","amountCents","paymentMethod","processor","processorIntentId","processorChargeId","processorStatus","referenceId","refundedFromId","paidByUserId","paidAt","notes","createdAt"],"additionalProperties":false}}},"required":["id","studentPersonId","feeCatalogId","schoolYearId","code","description","amountCents","balanceCents","status","dueOn","assessedOn","assessedByUserId","waivedByUserId","waivedAt","waivedReason","notes","createdAt","updatedAt","payments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/fees/{id}/void":{"post":{"summary":"Void a student fee (assessed in error; emits FeeVoided)","tags":["Fees"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"feeCatalogId":{"type":"string","format":"uuid","nullable":true},"feeCatalogCode":{"type":"string","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"description":{"type":"string"},"amountCents":{"type":"integer"},"balanceCents":{"type":"integer"},"paidCents":{"type":"integer"},"status":{"type":"string","enum":["open","partial","paid","void","waived"]},"dueOn":{"type":"string","format":"date","nullable":true},"assessedOn":{"type":"string","format":"date"},"assessedByUserId":{"type":"string","nullable":true},"waivedByUserId":{"type":"string","nullable":true},"waivedAt":{"type":"string","format":"date-time","nullable":true},"waivedReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentFeeId":{"type":"string","format":"uuid"},"amountCents":{"type":"integer"},"paymentMethod":{"type":"string","enum":["stripe","school_cash","cash","check","adjustment","refund"]},"processor":{"type":"string","enum":["stripe","manual","school_cash","adjustment"]},"processorIntentId":{"type":"string","nullable":true},"processorChargeId":{"type":"string","nullable":true},"processorStatus":{"type":"string","enum":["succeeded","pending","failed"],"nullable":true},"referenceId":{"type":"string","nullable":true},"refundedFromId":{"type":"string","format":"uuid","nullable":true},"paidByUserId":{"type":"string","nullable":true},"paidAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentFeeId","amountCents","paymentMethod","processor","processorIntentId","processorChargeId","processorStatus","referenceId","refundedFromId","paidByUserId","paidAt","notes","createdAt"],"additionalProperties":false}}},"required":["id","studentPersonId","feeCatalogId","schoolYearId","code","description","amountCents","balanceCents","status","dueOn","assessedOn","assessedByUserId","waivedByUserId","waivedAt","waivedReason","notes","createdAt","updatedAt","payments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/fees/reports/summary":{"get":{"summary":"District-wide fees summary (for business-office dashboard)","tags":["Fees"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"totalAssessedCents":{"type":"integer"},"totalCollectedCents":{"type":"integer"},"totalBalanceCents":{"type":"integer"},"totalWaivedCents":{"type":"integer"},"totalVoidedCents":{"type":"integer"},"openCount":{"type":"integer"},"paidCount":{"type":"integer"},"collectionRate":{"type":"number"}},"required":["totalAssessedCents","totalCollectedCents","totalBalanceCents","totalWaivedCents","totalVoidedCents","openCount","paidCount","collectionRate"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/fees/payments":{"get":{"summary":"List fee payments (includes refunds as negative rows)","tags":["Fees"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentFeeId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"string","enum":["stripe","manual","school_cash","adjustment"]},"in":"query","name":"processor","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentFeeId":{"type":"string","format":"uuid"},"amountCents":{"type":"integer"},"paymentMethod":{"type":"string","enum":["stripe","school_cash","cash","check","adjustment","refund"]},"processor":{"type":"string","enum":["stripe","manual","school_cash","adjustment"]},"processorIntentId":{"type":"string","nullable":true},"processorChargeId":{"type":"string","nullable":true},"processorStatus":{"type":"string","enum":["succeeded","pending","failed"],"nullable":true},"referenceId":{"type":"string","nullable":true},"refundedFromId":{"type":"string","format":"uuid","nullable":true},"paidByUserId":{"type":"string","nullable":true},"paidAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentFeeId","amountCents","paymentMethod","processor","processorIntentId","processorChargeId","processorStatus","referenceId","refundedFromId","paidByUserId","paidAt","notes","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/fees/{id}/payments":{"post":{"summary":"Record an in-office payment against a fee (emits FeePaid)","tags":["Fees"],"description":"Use for check, cash, school-cash (external), or manual adjustment payments. Online Stripe payments use the family endpoint which also finalizes the PaymentIntent.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amountCents":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":10000000},"paymentMethod":{"type":"string","enum":["cash","check","school_cash","adjustment"],"default":"check"},"referenceId":{"type":"string","maxLength":100},"notes":{"type":"string","maxLength":500}},"required":["amountCents"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentFeeId":{"type":"string","format":"uuid"},"amountCents":{"type":"integer"},"paymentMethod":{"type":"string","enum":["stripe","school_cash","cash","check","adjustment","refund"]},"processor":{"type":"string","enum":["stripe","manual","school_cash","adjustment"]},"processorIntentId":{"type":"string","nullable":true},"processorChargeId":{"type":"string","nullable":true},"processorStatus":{"type":"string","enum":["succeeded","pending","failed"],"nullable":true},"referenceId":{"type":"string","nullable":true},"refundedFromId":{"type":"string","format":"uuid","nullable":true},"paidByUserId":{"type":"string","nullable":true},"paidAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentFeeId","amountCents","paymentMethod","processor","processorIntentId","processorChargeId","processorStatus","referenceId","refundedFromId","paidByUserId","paidAt","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/fees/payments/{id}/refund":{"post":{"summary":"Refund a previous payment (emits FeeRefunded)","tags":["Fees"],"description":"Stored as a negative `FeePayment` that points at the original via `refundedFromId`. Refuses over-refund.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amountCents":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":10000000},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentFeeId":{"type":"string","format":"uuid"},"amountCents":{"type":"integer"},"paymentMethod":{"type":"string","enum":["stripe","school_cash","cash","check","adjustment","refund"]},"processor":{"type":"string","enum":["stripe","manual","school_cash","adjustment"]},"processorIntentId":{"type":"string","nullable":true},"processorChargeId":{"type":"string","nullable":true},"processorStatus":{"type":"string","enum":["succeeded","pending","failed"],"nullable":true},"referenceId":{"type":"string","nullable":true},"refundedFromId":{"type":"string","format":"uuid","nullable":true},"paidByUserId":{"type":"string","nullable":true},"paidAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentFeeId","amountCents","paymentMethod","processor","processorIntentId","processorChargeId","processorStatus","referenceId","refundedFromId","paidByUserId","paidAt","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/students/{id}/fees":{"get":{"summary":"Guardianed student's fees — balance, open charges, payment history","tags":["Parent Portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"totalBalanceCents":{"type":"integer"},"openFeeCount":{"type":"integer"},"overdueFeeCount":{"type":"integer"},"fees":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"feeCatalogId":{"type":"string","format":"uuid","nullable":true},"feeCatalogCode":{"type":"string","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"description":{"type":"string"},"amountCents":{"type":"integer"},"balanceCents":{"type":"integer"},"paidCents":{"type":"integer"},"status":{"type":"string","enum":["open","partial","paid","void","waived"]},"dueOn":{"type":"string","format":"date","nullable":true},"assessedOn":{"type":"string","format":"date"},"assessedByUserId":{"type":"string","nullable":true},"waivedByUserId":{"type":"string","nullable":true},"waivedAt":{"type":"string","format":"date-time","nullable":true},"waivedReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","feeCatalogId","schoolYearId","code","description","amountCents","balanceCents","status","dueOn","assessedOn","assessedByUserId","waivedByUserId","waivedAt","waivedReason","notes","createdAt","updatedAt"],"additionalProperties":false}}},"required":["studentPersonId","studentName","totalBalanceCents","openFeeCount","overdueFeeCount","fees"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/student/me/fees":{"get":{"summary":"Signed-in student's fees (read-only)","tags":["Student Portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"totalBalanceCents":{"type":"integer"},"openFeeCount":{"type":"integer"},"overdueFeeCount":{"type":"integer"},"fees":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"studentName":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"feeCatalogId":{"type":"string","format":"uuid","nullable":true},"feeCatalogCode":{"type":"string","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"description":{"type":"string"},"amountCents":{"type":"integer"},"balanceCents":{"type":"integer"},"paidCents":{"type":"integer"},"status":{"type":"string","enum":["open","partial","paid","void","waived"]},"dueOn":{"type":"string","format":"date","nullable":true},"assessedOn":{"type":"string","format":"date"},"assessedByUserId":{"type":"string","nullable":true},"waivedByUserId":{"type":"string","nullable":true},"waivedAt":{"type":"string","format":"date-time","nullable":true},"waivedReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","studentPersonId","feeCatalogId","schoolYearId","code","description","amountCents","balanceCents","status","dueOn","assessedOn","assessedByUserId","waivedByUserId","waivedAt","waivedReason","notes","createdAt","updatedAt"],"additionalProperties":false}}},"required":["studentPersonId","studentName","totalBalanceCents","openFeeCount","overdueFeeCount","fees"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/parent/fees/{id}/pay":{"post":{"summary":"Finalize an online (Stripe) payment against a fee (emits FeePaid)","tags":["Parent Portal"],"description":"Called after the front end confirms a Stripe PaymentIntent. We record the payment, finalize status, and bump the ledger. The webhook handler is idempotent against `processorIntentId`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amountCents":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":10000000},"processorIntentId":{"type":"string","minLength":4,"maxLength":100},"processorChargeId":{"type":"string","maxLength":100},"processorStatus":{"type":"string","enum":["succeeded","pending","failed"],"default":"succeeded"},"notes":{"type":"string","maxLength":500}},"required":["amountCents","processorIntentId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"studentFeeId":{"type":"string","format":"uuid"},"amountCents":{"type":"integer"},"paymentMethod":{"type":"string","enum":["stripe","school_cash","cash","check","adjustment","refund"]},"processor":{"type":"string","enum":["stripe","manual","school_cash","adjustment"]},"processorIntentId":{"type":"string","nullable":true},"processorChargeId":{"type":"string","nullable":true},"processorStatus":{"type":"string","enum":["succeeded","pending","failed"],"nullable":true},"referenceId":{"type":"string","nullable":true},"refundedFromId":{"type":"string","format":"uuid","nullable":true},"paidByUserId":{"type":"string","nullable":true},"paidAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","studentFeeId","amountCents","paymentMethod","processor","processorIntentId","processorChargeId","processorStatus","referenceId","refundedFromId","paidByUserId","paidAt","notes","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/fees/{id}/checkout":{"post":{"summary":"Create a Stripe hosted-checkout session for a fee (parent portal)","tags":["Fees"],"description":"Creates a Stripe Checkout Session for the specified fee. The response contains `sessionUrl` — the parent portal navigates to this URL. Stripe handles the card form. On completion, Stripe calls our webhook which projects the payment into the fee ledger.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"successPath":{"type":"string","minLength":1,"maxLength":500,"default":"/parent"},"cancelPath":{"type":"string","minLength":1,"maxLength":500,"default":"/parent"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"sessionUrl":{"type":"string","format":"uri"},"sessionId":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"amountCents":{"type":"integer"},"currency":{"type":"string"}},"required":["sessionUrl","sessionId","expiresAt","amountCents","currency"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/fees/payments/reconciliation":{"get":{"summary":"Payment reconciliation — online vs. in-office totals (admin GL export)","tags":["Fees"],"description":"Aggregate payment totals by processor channel for a given date range. Used by the business office to reconcile Stripe settlements against in-office deposits.","parameters":[{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"totalCollectedCents":{"type":"integer"},"onlineCollectedCents":{"type":"integer"},"inOfficeCollectedCents":{"type":"integer"},"totalRefundedCents":{"type":"integer"},"onlineCount":{"type":"integer"},"inOfficeCount":{"type":"integer"},"refundCount":{"type":"integer"},"byProcessor":{"type":"array","items":{"type":"object","properties":{"processor":{"type":"string","enum":["stripe","manual","school_cash","adjustment"]},"count":{"type":"integer"},"totalCents":{"type":"integer"}},"required":["processor","count","totalCents"],"additionalProperties":false}},"periodFrom":{"type":"string","format":"date","nullable":true},"periodTo":{"type":"string","format":"date","nullable":true}},"required":["totalCollectedCents","onlineCollectedCents","inOfficeCollectedCents","totalRefundedCents","onlineCount","inOfficeCount","refundCount","byProcessor","periodFrom","periodTo"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/payments/webhook/stripe":{"post":{"tags":["Webhooks"],"description":"Stripe payment-event webhook (HMAC-SHA256 via Stripe-Signature header).","responses":{"200":{"description":"Default Response"}}}},"/sub/profiles":{"get":{"summary":"List substitute teachers in the district pool","tags":["Substitutes"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["active","inactive","archived"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","maxLength":100},"in":"query","name":"search","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"personName":{"type":"string"},"status":{"type":"string","enum":["active","inactive","archived"]},"gradeBands":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"preferredSchoolIds":{"type":"array","items":{"type":"string","format":"uuid"}},"certifications":{"type":"array","items":{"type":"string"}},"dailyRateCents":{"type":"integer"},"halfDayRateCents":{"type":"integer"},"minNoticeMinutes":{"type":"integer"},"bio":{"type":"string","nullable":true},"lastRefreshedAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","personId","status","gradeBands","subjectCodes","preferredSchoolIds","certifications","dailyRateCents","halfDayRateCents","minNoticeMinutes","bio","lastRefreshedAt","notes","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Add a substitute to the pool (emits SubstituteProfileCreated)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"gradeBands":{"type":"array","items":{"type":"string","maxLength":20},"default":[]},"subjectCodes":{"type":"array","items":{"type":"string","maxLength":20},"default":[]},"preferredSchoolIds":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"certifications":{"type":"array","items":{"type":"string","maxLength":60},"default":[]},"dailyRateCents":{"type":"integer","minimum":0,"default":0},"halfDayRateCents":{"type":"integer","minimum":0,"default":0},"minNoticeMinutes":{"type":"integer","minimum":0,"maximum":10080,"default":60},"bio":{"type":"string","maxLength":2000},"notes":{"type":"string","maxLength":500}},"required":["personId"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"personName":{"type":"string"},"status":{"type":"string","enum":["active","inactive","archived"]},"gradeBands":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"preferredSchoolIds":{"type":"array","items":{"type":"string","format":"uuid"}},"certifications":{"type":"array","items":{"type":"string"}},"dailyRateCents":{"type":"integer"},"halfDayRateCents":{"type":"integer"},"minNoticeMinutes":{"type":"integer"},"bio":{"type":"string","nullable":true},"lastRefreshedAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","personId","status","gradeBands","subjectCodes","preferredSchoolIds","certifications","dailyRateCents","halfDayRateCents","minNoticeMinutes","bio","lastRefreshedAt","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/profiles/{id}":{"get":{"summary":"Get a substitute profile","tags":["Substitutes"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"personName":{"type":"string"},"status":{"type":"string","enum":["active","inactive","archived"]},"gradeBands":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"preferredSchoolIds":{"type":"array","items":{"type":"string","format":"uuid"}},"certifications":{"type":"array","items":{"type":"string"}},"dailyRateCents":{"type":"integer"},"halfDayRateCents":{"type":"integer"},"minNoticeMinutes":{"type":"integer"},"bio":{"type":"string","nullable":true},"lastRefreshedAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","personId","status","gradeBands","subjectCodes","preferredSchoolIds","certifications","dailyRateCents","halfDayRateCents","minNoticeMinutes","bio","lastRefreshedAt","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a substitute profile (emits SubstituteProfileUpdated)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"gradeBands":{"type":"array","items":{"type":"string","maxLength":20},"default":[]},"subjectCodes":{"type":"array","items":{"type":"string","maxLength":20},"default":[]},"preferredSchoolIds":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"certifications":{"type":"array","items":{"type":"string","maxLength":60},"default":[]},"dailyRateCents":{"type":"integer","minimum":0,"default":0},"halfDayRateCents":{"type":"integer","minimum":0,"default":0},"minNoticeMinutes":{"type":"integer","minimum":0,"maximum":10080,"default":60},"bio":{"type":"string","maxLength":2000},"notes":{"type":"string","maxLength":500},"status":{"type":"string","enum":["active","inactive","archived"]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"personName":{"type":"string"},"status":{"type":"string","enum":["active","inactive","archived"]},"gradeBands":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"preferredSchoolIds":{"type":"array","items":{"type":"string","format":"uuid"}},"certifications":{"type":"array","items":{"type":"string"}},"dailyRateCents":{"type":"integer"},"halfDayRateCents":{"type":"integer"},"minNoticeMinutes":{"type":"integer"},"bio":{"type":"string","nullable":true},"lastRefreshedAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","personId","status","gradeBands","subjectCodes","preferredSchoolIds","certifications","dailyRateCents","halfDayRateCents","minNoticeMinutes","bio","lastRefreshedAt","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/profiles/{id}/archive":{"post":{"summary":"Archive a substitute (emits SubstituteProfileArchived)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","maxLength":500},"reason":{"type":"string","maxLength":500}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"personName":{"type":"string"},"status":{"type":"string","enum":["active","inactive","archived"]},"gradeBands":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"preferredSchoolIds":{"type":"array","items":{"type":"string","format":"uuid"}},"certifications":{"type":"array","items":{"type":"string"}},"dailyRateCents":{"type":"integer"},"halfDayRateCents":{"type":"integer"},"minNoticeMinutes":{"type":"integer"},"bio":{"type":"string","nullable":true},"lastRefreshedAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","personId","status","gradeBands","subjectCodes","preferredSchoolIds","certifications","dailyRateCents","halfDayRateCents","minNoticeMinutes","bio","lastRefreshedAt","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/profiles/me":{"get":{"summary":"Load the current user's own substitute profile (sub portal)","tags":["Substitutes"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"personName":{"type":"string"},"status":{"type":"string","enum":["active","inactive","archived"]},"gradeBands":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"preferredSchoolIds":{"type":"array","items":{"type":"string","format":"uuid"}},"certifications":{"type":"array","items":{"type":"string"}},"dailyRateCents":{"type":"integer"},"halfDayRateCents":{"type":"integer"},"minNoticeMinutes":{"type":"integer"},"bio":{"type":"string","nullable":true},"lastRefreshedAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","personId","status","gradeBands","subjectCodes","preferredSchoolIds","certifications","dailyRateCents","halfDayRateCents","minNoticeMinutes","bio","lastRefreshedAt","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/absences":{"get":{"summary":"List staff absences","tags":["Substitutes"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"staffPersonId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Report a staff absence (emits StaffAbsenceReported)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"staffPersonId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean","default":false},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","maxLength":500},"mustFill":{"type":"boolean","default":true}},"required":["staffPersonId","startDate","endDate","reasonCode"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"autoJobIds":{"type":"array","items":{"type":"string","format":"uuid"}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/absences/mine":{"get":{"summary":"List the acting teacher's own absences (scoped server-side by personId)","tags":["Substitutes"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/absences/{id}":{"get":{"summary":"Get a staff absence","tags":["Substitutes"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"autoJobIds":{"type":"array","items":{"type":"string","format":"uuid"}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/absences/report-mine":{"post":{"summary":"Report the acting teacher's own absence (scoped server-side by personId)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolId":{"type":"string","format":"uuid"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean","default":false},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","maxLength":500},"mustFill":{"type":"boolean","default":true}},"required":["startDate","endDate","reasonCode"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"autoJobIds":{"type":"array","items":{"type":"string","format":"uuid"}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/absences/{id}/approve":{"post":{"summary":"Approve a reported absence (emits StaffAbsenceApproved)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"autoJobIds":{"type":"array","items":{"type":"string","format":"uuid"}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/absences/{id}/deny":{"post":{"summary":"Deny a reported absence (emits StaffAbsenceDenied)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"autoJobIds":{"type":"array","items":{"type":"string","format":"uuid"}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/absences/{id}/cancel":{"post":{"summary":"Cancel a reported absence (emits StaffAbsenceCancelled + SubJobCancelled per open job)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"autoJobIds":{"type":"array","items":{"type":"string","format":"uuid"}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/jobs":{"get":{"summary":"List sub jobs","tags":["Substitutes"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["open","offered","filled","cancelled","completed"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"absenceId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"absenceId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"workDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"payRateCents":{"type":"integer"},"status":{"type":"string","enum":["open","offered","filled","cancelled","completed"]},"postedByUserId":{"type":"string","format":"uuid","nullable":true},"postedAt":{"type":"string","format":"date-time"},"filledByProfileId":{"type":"string","format":"uuid","nullable":true},"filledByName":{"type":"string","nullable":true},"filledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"]},"matchScore":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"declineReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","status","matchScore","expiresAt","respondedAt","declineReason","createdAt","updatedAt"],"additionalProperties":false}},"assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"plannedStart":{"type":"string","format":"date-time"},"plannedEnd":{"type":"string","format":"date-time"},"actualStart":{"type":"string","format":"date-time","nullable":true},"actualEnd":{"type":"string","format":"date-time","nullable":true},"payrollStatus":{"type":"string","enum":["approved","adjusted","paid"]},"payoutCents":{"type":"integer"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","plannedStart","plannedEnd","actualStart","actualEnd","payrollStatus","payoutCents","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"absence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","absenceId","schoolId","sectionIds","workDate","halfDay","payRateCents","status","postedByUserId","postedAt","filledByProfileId","filledAt","cancelledReason","cancelledAt","notes","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Post a sub job against an approved absence (emits SubJobPosted)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"absenceId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"workDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean","default":false},"payRateCents":{"type":"integer","minimum":0},"notes":{"type":"string","maxLength":500}},"required":["absenceId","workDate","payRateCents"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"absenceId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"workDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"payRateCents":{"type":"integer"},"status":{"type":"string","enum":["open","offered","filled","cancelled","completed"]},"postedByUserId":{"type":"string","format":"uuid","nullable":true},"postedAt":{"type":"string","format":"date-time"},"filledByProfileId":{"type":"string","format":"uuid","nullable":true},"filledByName":{"type":"string","nullable":true},"filledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"]},"matchScore":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"declineReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","status","matchScore","expiresAt","respondedAt","declineReason","createdAt","updatedAt"],"additionalProperties":false}},"assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"plannedStart":{"type":"string","format":"date-time"},"plannedEnd":{"type":"string","format":"date-time"},"actualStart":{"type":"string","format":"date-time","nullable":true},"actualEnd":{"type":"string","format":"date-time","nullable":true},"payrollStatus":{"type":"string","enum":["approved","adjusted","paid"]},"payoutCents":{"type":"integer"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","plannedStart","plannedEnd","actualStart","actualEnd","payrollStatus","payoutCents","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"absence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","absenceId","schoolId","sectionIds","workDate","halfDay","payRateCents","status","postedByUserId","postedAt","filledByProfileId","filledAt","cancelledReason","cancelledAt","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/jobs/{id}":{"get":{"summary":"Get a sub job with offers + assignment + absence","tags":["Substitutes"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"absenceId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"workDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"payRateCents":{"type":"integer"},"status":{"type":"string","enum":["open","offered","filled","cancelled","completed"]},"postedByUserId":{"type":"string","format":"uuid","nullable":true},"postedAt":{"type":"string","format":"date-time"},"filledByProfileId":{"type":"string","format":"uuid","nullable":true},"filledByName":{"type":"string","nullable":true},"filledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"]},"matchScore":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"declineReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","status","matchScore","expiresAt","respondedAt","declineReason","createdAt","updatedAt"],"additionalProperties":false}},"assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"plannedStart":{"type":"string","format":"date-time"},"plannedEnd":{"type":"string","format":"date-time"},"actualStart":{"type":"string","format":"date-time","nullable":true},"actualEnd":{"type":"string","format":"date-time","nullable":true},"payrollStatus":{"type":"string","enum":["approved","adjusted","paid"]},"payoutCents":{"type":"integer"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","plannedStart","plannedEnd","actualStart","actualEnd","payrollStatus","payoutCents","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"absence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","absenceId","schoolId","sectionIds","workDate","halfDay","payRateCents","status","postedByUserId","postedAt","filledByProfileId","filledAt","cancelledReason","cancelledAt","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/jobs/{id}/offer":{"post":{"summary":"Offer a sub job to a specific substitute (emits SubJobOffered)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"substituteProfileId":{"type":"string","format":"uuid"},"matchScore":{"type":"integer","minimum":0,"maximum":100,"default":50},"expiresAt":{"type":"string","format":"date-time"}},"required":["substituteProfileId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"absenceId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"workDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"payRateCents":{"type":"integer"},"status":{"type":"string","enum":["open","offered","filled","cancelled","completed"]},"postedByUserId":{"type":"string","format":"uuid","nullable":true},"postedAt":{"type":"string","format":"date-time"},"filledByProfileId":{"type":"string","format":"uuid","nullable":true},"filledByName":{"type":"string","nullable":true},"filledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"]},"matchScore":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"declineReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","status","matchScore","expiresAt","respondedAt","declineReason","createdAt","updatedAt"],"additionalProperties":false}},"assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"plannedStart":{"type":"string","format":"date-time"},"plannedEnd":{"type":"string","format":"date-time"},"actualStart":{"type":"string","format":"date-time","nullable":true},"actualEnd":{"type":"string","format":"date-time","nullable":true},"payrollStatus":{"type":"string","enum":["approved","adjusted","paid"]},"payoutCents":{"type":"integer"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","plannedStart","plannedEnd","actualStart","actualEnd","payrollStatus","payoutCents","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"absence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","absenceId","schoolId","sectionIds","workDate","halfDay","payRateCents","status","postedByUserId","postedAt","filledByProfileId","filledAt","cancelledReason","cancelledAt","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/jobs/{id}/assign":{"post":{"summary":"Manually assign a sub to a job (emits SubJobFilled; rescinds pending offers)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"substituteProfileId":{"type":"string","format":"uuid"}},"required":["substituteProfileId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"absenceId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"workDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"payRateCents":{"type":"integer"},"status":{"type":"string","enum":["open","offered","filled","cancelled","completed"]},"postedByUserId":{"type":"string","format":"uuid","nullable":true},"postedAt":{"type":"string","format":"date-time"},"filledByProfileId":{"type":"string","format":"uuid","nullable":true},"filledByName":{"type":"string","nullable":true},"filledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"]},"matchScore":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"declineReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","status","matchScore","expiresAt","respondedAt","declineReason","createdAt","updatedAt"],"additionalProperties":false}},"assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"plannedStart":{"type":"string","format":"date-time"},"plannedEnd":{"type":"string","format":"date-time"},"actualStart":{"type":"string","format":"date-time","nullable":true},"actualEnd":{"type":"string","format":"date-time","nullable":true},"payrollStatus":{"type":"string","enum":["approved","adjusted","paid"]},"payoutCents":{"type":"integer"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","plannedStart","plannedEnd","actualStart","actualEnd","payrollStatus","payoutCents","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"absence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","absenceId","schoolId","sectionIds","workDate","halfDay","payRateCents","status","postedByUserId","postedAt","filledByProfileId","filledAt","cancelledReason","cancelledAt","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/jobs/{id}/cancel":{"post":{"summary":"Cancel a sub job (emits SubJobCancelled; rescinds pending offers)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"absenceId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"workDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"payRateCents":{"type":"integer"},"status":{"type":"string","enum":["open","offered","filled","cancelled","completed"]},"postedByUserId":{"type":"string","format":"uuid","nullable":true},"postedAt":{"type":"string","format":"date-time"},"filledByProfileId":{"type":"string","format":"uuid","nullable":true},"filledByName":{"type":"string","nullable":true},"filledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"]},"matchScore":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"declineReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","status","matchScore","expiresAt","respondedAt","declineReason","createdAt","updatedAt"],"additionalProperties":false}},"assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"plannedStart":{"type":"string","format":"date-time"},"plannedEnd":{"type":"string","format":"date-time"},"actualStart":{"type":"string","format":"date-time","nullable":true},"actualEnd":{"type":"string","format":"date-time","nullable":true},"payrollStatus":{"type":"string","enum":["approved","adjusted","paid"]},"payoutCents":{"type":"integer"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","plannedStart","plannedEnd","actualStart","actualEnd","payrollStatus","payoutCents","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"absence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","absenceId","schoolId","sectionIds","workDate","halfDay","payRateCents","status","postedByUserId","postedAt","filledByProfileId","filledAt","cancelledReason","cancelledAt","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/jobs/{id}/complete":{"post":{"summary":"Close out a filled job with clock-in/out (emits SubJobCompleted)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"actualStart":{"type":"string","format":"date-time"},"actualEnd":{"type":"string","format":"date-time"},"payoutCents":{"type":"integer","minimum":0},"notes":{"type":"string","maxLength":500}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"absenceId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"workDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"payRateCents":{"type":"integer"},"status":{"type":"string","enum":["open","offered","filled","cancelled","completed"]},"postedByUserId":{"type":"string","format":"uuid","nullable":true},"postedAt":{"type":"string","format":"date-time"},"filledByProfileId":{"type":"string","format":"uuid","nullable":true},"filledByName":{"type":"string","nullable":true},"filledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"]},"matchScore":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"declineReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","status","matchScore","expiresAt","respondedAt","declineReason","createdAt","updatedAt"],"additionalProperties":false}},"assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"plannedStart":{"type":"string","format":"date-time"},"plannedEnd":{"type":"string","format":"date-time"},"actualStart":{"type":"string","format":"date-time","nullable":true},"actualEnd":{"type":"string","format":"date-time","nullable":true},"payrollStatus":{"type":"string","enum":["approved","adjusted","paid"]},"payoutCents":{"type":"integer"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","plannedStart","plannedEnd","actualStart","actualEnd","payrollStatus","payoutCents","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"absence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","absenceId","schoolId","sectionIds","workDate","halfDay","payRateCents","status","postedByUserId","postedAt","filledByProfileId","filledAt","cancelledReason","cancelledAt","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/jobs/{id}/auto-match":{"post":{"summary":"Rank substitute pool against a job (emits SubJobAutoMatched; optionally sends offers)","tags":["Substitutes"],"description":"Scores all active substitutes against availability, school preference, certifications, and recent load. Returns ranked candidates. When sendOffers=true, dispatches offers to the top sendTopN candidates automatically. Offer dispatch is idempotent — safe to run multiple times.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"in":"query","name":"limit","required":false},{"schema":{"type":"string","enum":["true","false","1","0"],"default":"false"},"in":"query","name":"sendOffers","required":false},{"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"in":"query","name":"sendTopN","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"jobId":{"type":"string","format":"uuid"},"candidates":{"type":"array","items":{"type":"object","properties":{"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"score":{"type":"integer","minimum":0,"maximum":100},"isAvailable":{"type":"boolean"},"schoolPreferred":{"type":"boolean"},"hasCertifications":{"type":"boolean"},"recentJobCount":{"type":"integer"},"reasons":{"type":"array","items":{"type":"string"}},"offerId":{"type":"string","format":"uuid"}},"required":["substituteProfileId","score","isAvailable","schoolPreferred","hasCertifications","recentJobCount","reasons"],"additionalProperties":false}},"offersCreated":{"type":"integer"}},"required":["jobId","candidates","offersCreated"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/reports/summary":{"get":{"summary":"District-wide sub-pool KPIs (fill rate, time-to-fill, unfilled mustFill)","tags":["Substitutes"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"poolCount":{"type":"integer"},"activePoolCount":{"type":"integer"},"openAbsenceCount":{"type":"integer"},"openJobCount":{"type":"integer"},"filledTodayCount":{"type":"integer"},"fillRate30d":{"type":"number"},"avgTimeToFillMinutes30d":{"type":"integer"},"unfilledMustFillCount":{"type":"integer"}},"required":["poolCount","activePoolCount","openAbsenceCount","openJobCount","filledTodayCount","fillRate30d","avgTimeToFillMinutes30d","unfilledMustFillCount"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/portal/my-board":{"get":{"summary":"List the acting substitute's open offers, accepted assignments, and general job board","tags":["Substitutes"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"openJobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"absenceId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"workDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"payRateCents":{"type":"integer"},"status":{"type":"string","enum":["open","offered","filled","cancelled","completed"]},"postedByUserId":{"type":"string","format":"uuid","nullable":true},"postedAt":{"type":"string","format":"date-time"},"filledByProfileId":{"type":"string","format":"uuid","nullable":true},"filledByName":{"type":"string","nullable":true},"filledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"]},"matchScore":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"declineReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","status","matchScore","expiresAt","respondedAt","declineReason","createdAt","updatedAt"],"additionalProperties":false}},"assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"plannedStart":{"type":"string","format":"date-time"},"plannedEnd":{"type":"string","format":"date-time"},"actualStart":{"type":"string","format":"date-time","nullable":true},"actualEnd":{"type":"string","format":"date-time","nullable":true},"payrollStatus":{"type":"string","enum":["approved","adjusted","paid"]},"payoutCents":{"type":"integer"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","plannedStart","plannedEnd","actualStart","actualEnd","payrollStatus","payoutCents","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"absence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"isEligible":{"type":"boolean"},"hasOfferForMe":{"type":"boolean"},"myOfferStatus":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"],"nullable":true},"myOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"matchScore":{"type":"integer"}},"required":["id","expiresAt","matchScore"],"additionalProperties":false,"nullable":true}},"required":["id","absenceId","schoolId","sectionIds","workDate","halfDay","payRateCents","status","postedByUserId","postedAt","filledByProfileId","filledAt","cancelledReason","cancelledAt","notes","createdAt","updatedAt","isEligible","hasOfferForMe","myOfferStatus"],"additionalProperties":false}},"myOffers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"absenceId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"workDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"payRateCents":{"type":"integer"},"status":{"type":"string","enum":["open","offered","filled","cancelled","completed"]},"postedByUserId":{"type":"string","format":"uuid","nullable":true},"postedAt":{"type":"string","format":"date-time"},"filledByProfileId":{"type":"string","format":"uuid","nullable":true},"filledByName":{"type":"string","nullable":true},"filledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"]},"matchScore":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"declineReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","status","matchScore","expiresAt","respondedAt","declineReason","createdAt","updatedAt"],"additionalProperties":false}},"assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"plannedStart":{"type":"string","format":"date-time"},"plannedEnd":{"type":"string","format":"date-time"},"actualStart":{"type":"string","format":"date-time","nullable":true},"actualEnd":{"type":"string","format":"date-time","nullable":true},"payrollStatus":{"type":"string","enum":["approved","adjusted","paid"]},"payoutCents":{"type":"integer"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","plannedStart","plannedEnd","actualStart","actualEnd","payrollStatus","payoutCents","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"absence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"isEligible":{"type":"boolean"},"hasOfferForMe":{"type":"boolean"},"myOfferStatus":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"],"nullable":true},"myOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"matchScore":{"type":"integer"}},"required":["id","expiresAt","matchScore"],"additionalProperties":false,"nullable":true}},"required":["id","absenceId","schoolId","sectionIds","workDate","halfDay","payRateCents","status","postedByUserId","postedAt","filledByProfileId","filledAt","cancelledReason","cancelledAt","notes","createdAt","updatedAt","isEligible","hasOfferForMe","myOfferStatus"],"additionalProperties":false}},"myAssignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"absenceId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"workDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"payRateCents":{"type":"integer"},"status":{"type":"string","enum":["open","offered","filled","cancelled","completed"]},"postedByUserId":{"type":"string","format":"uuid","nullable":true},"postedAt":{"type":"string","format":"date-time"},"filledByProfileId":{"type":"string","format":"uuid","nullable":true},"filledByName":{"type":"string","nullable":true},"filledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"]},"matchScore":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"declineReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","status","matchScore","expiresAt","respondedAt","declineReason","createdAt","updatedAt"],"additionalProperties":false}},"assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"plannedStart":{"type":"string","format":"date-time"},"plannedEnd":{"type":"string","format":"date-time"},"actualStart":{"type":"string","format":"date-time","nullable":true},"actualEnd":{"type":"string","format":"date-time","nullable":true},"payrollStatus":{"type":"string","enum":["approved","adjusted","paid"]},"payoutCents":{"type":"integer"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","plannedStart","plannedEnd","actualStart","actualEnd","payrollStatus","payoutCents","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"absence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"isEligible":{"type":"boolean"},"hasOfferForMe":{"type":"boolean"},"myOfferStatus":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"],"nullable":true},"myOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"matchScore":{"type":"integer"}},"required":["id","expiresAt","matchScore"],"additionalProperties":false,"nullable":true}},"required":["id","absenceId","schoolId","sectionIds","workDate","halfDay","payRateCents","status","postedByUserId","postedAt","filledByProfileId","filledAt","cancelledReason","cancelledAt","notes","createdAt","updatedAt","isEligible","hasOfferForMe","myOfferStatus"],"additionalProperties":false}},"notOnboarded":{"type":"boolean","default":false},"onboardingContact":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email","nullable":true},"role":{"type":"string"}},"required":["name","email","role"],"additionalProperties":false,"nullable":true}},"required":["openJobs","myOffers","myAssignments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/portal/offers/{id}/accept":{"post":{"summary":"Accept a pending offer (emits SubJobOfferAccepted + SubJobFilled)","tags":["Substitutes"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"absenceId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"workDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"payRateCents":{"type":"integer"},"status":{"type":"string","enum":["open","offered","filled","cancelled","completed"]},"postedByUserId":{"type":"string","format":"uuid","nullable":true},"postedAt":{"type":"string","format":"date-time"},"filledByProfileId":{"type":"string","format":"uuid","nullable":true},"filledByName":{"type":"string","nullable":true},"filledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"]},"matchScore":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"declineReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","status","matchScore","expiresAt","respondedAt","declineReason","createdAt","updatedAt"],"additionalProperties":false}},"assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"plannedStart":{"type":"string","format":"date-time"},"plannedEnd":{"type":"string","format":"date-time"},"actualStart":{"type":"string","format":"date-time","nullable":true},"actualEnd":{"type":"string","format":"date-time","nullable":true},"payrollStatus":{"type":"string","enum":["approved","adjusted","paid"]},"payoutCents":{"type":"integer"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","plannedStart","plannedEnd","actualStart","actualEnd","payrollStatus","payoutCents","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"absence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","absenceId","schoolId","sectionIds","workDate","halfDay","payRateCents","status","postedByUserId","postedAt","filledByProfileId","filledAt","cancelledReason","cancelledAt","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/sub/portal/offers/{id}/decline":{"post":{"summary":"Decline a pending offer (emits SubJobOfferDeclined)","tags":["Substitutes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":300}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"absenceId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"sectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"workDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"payRateCents":{"type":"integer"},"status":{"type":"string","enum":["open","offered","filled","cancelled","completed"]},"postedByUserId":{"type":"string","format":"uuid","nullable":true},"postedAt":{"type":"string","format":"date-time"},"filledByProfileId":{"type":"string","format":"uuid","nullable":true},"filledByName":{"type":"string","nullable":true},"filledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","declined","expired","rescinded"]},"matchScore":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"declineReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","status","matchScore","expiresAt","respondedAt","declineReason","createdAt","updatedAt"],"additionalProperties":false}},"assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"substituteProfileId":{"type":"string","format":"uuid"},"substituteName":{"type":"string"},"plannedStart":{"type":"string","format":"date-time"},"plannedEnd":{"type":"string","format":"date-time"},"actualStart":{"type":"string","format":"date-time","nullable":true},"actualEnd":{"type":"string","format":"date-time","nullable":true},"payrollStatus":{"type":"string","enum":["approved","adjusted","paid"]},"payoutCents":{"type":"integer"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","jobId","substituteProfileId","plannedStart","plannedEnd","actualStart","actualEnd","payrollStatus","payoutCents","notes","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"absence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"staffName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"halfDay":{"type":"boolean"},"reasonCode":{"type":"string","enum":["sick","personal","pd","jury","bereavement","fmla","other"]},"reasonNotes":{"type":"string","nullable":true},"mustFill":{"type":"boolean"},"status":{"type":"string","enum":["submitted","approved","denied","cancelled"]},"approvedByUserId":{"type":"string","format":"uuid","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"denyReason":{"type":"string","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"jobCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","staffPersonId","schoolId","startDate","endDate","halfDay","reasonCode","reasonNotes","mustFill","status","approvedByUserId","approvedAt","denyReason","cancelledAt","createdAt","updatedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","absenceId","schoolId","sectionIds","workDate","halfDay","payRateCents","status","postedByUserId","postedAt","filledByProfileId","filledAt","cancelledReason","cancelledAt","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/certs":{"get":{"summary":"List teacher certifications","tags":["Certifications"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"personId","required":false},{"schema":{"type":"string","enum":["active","expired","suspended","revoked","pending"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["teaching","administrative","specialist","emergency","substitute","other"]},"in":"query","name":"category","required":false},{"schema":{"type":"string","minLength":2,"maxLength":2},"in":"query","name":"stateCode","required":false},{"schema":{"type":"integer","minimum":1,"maximum":365},"in":"query","name":"expiresWithinDays","required":false},{"schema":{"type":"string","maxLength":100},"in":"query","name":"search","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"personName":{"type":"string"},"stateCode":{"type":"string","minLength":2,"maxLength":2},"category":{"type":"string","enum":["teaching","administrative","specialist","emergency","substitute","other"]},"certCode":{"type":"string"},"certLabel":{"type":"string"},"gradeBands":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"certNumber":{"type":"string","nullable":true},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["active","expired","suspended","revoked","pending"]},"source":{"type":"string","enum":["manual","doe_import","self_report"]},"documentUrl":{"type":"string","format":"uri","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","personId","stateCode","category","certCode","certLabel","gradeBands","subjectCodes","certNumber","issuedAt","expiresAt","status","source","documentUrl","notes","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Record a certification (emits TeacherCertificationCreated)","tags":["Certifications"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"stateCode":{"type":"string","minLength":2,"maxLength":2},"category":{"type":"string","enum":["teaching","administrative","specialist","emergency","substitute","other"]},"certCode":{"type":"string","minLength":1,"maxLength":64},"certLabel":{"type":"string","minLength":1,"maxLength":200},"gradeBands":{"type":"array","items":{"type":"string","maxLength":20},"default":[]},"subjectCodes":{"type":"array","items":{"type":"string","maxLength":20},"default":[]},"certNumber":{"type":"string","maxLength":64},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["active","expired","suspended","revoked","pending"],"default":"active"},"source":{"type":"string","enum":["manual","doe_import","self_report"],"default":"manual"},"documentUrl":{"type":"string","format":"uri","maxLength":500},"notes":{"type":"string","maxLength":500}},"required":["personId","stateCode","category","certCode","certLabel","issuedAt"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"personName":{"type":"string"},"stateCode":{"type":"string","minLength":2,"maxLength":2},"category":{"type":"string","enum":["teaching","administrative","specialist","emergency","substitute","other"]},"certCode":{"type":"string"},"certLabel":{"type":"string"},"gradeBands":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"certNumber":{"type":"string","nullable":true},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["active","expired","suspended","revoked","pending"]},"source":{"type":"string","enum":["manual","doe_import","self_report"]},"documentUrl":{"type":"string","format":"uri","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","personId","stateCode","category","certCode","certLabel","gradeBands","subjectCodes","certNumber","issuedAt","expiresAt","status","source","documentUrl","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/certs/{id}":{"get":{"summary":"Get a single certification","tags":["Certifications"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"personName":{"type":"string"},"stateCode":{"type":"string","minLength":2,"maxLength":2},"category":{"type":"string","enum":["teaching","administrative","specialist","emergency","substitute","other"]},"certCode":{"type":"string"},"certLabel":{"type":"string"},"gradeBands":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"certNumber":{"type":"string","nullable":true},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["active","expired","suspended","revoked","pending"]},"source":{"type":"string","enum":["manual","doe_import","self_report"]},"documentUrl":{"type":"string","format":"uri","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","personId","stateCode","category","certCode","certLabel","gradeBands","subjectCodes","certNumber","issuedAt","expiresAt","status","source","documentUrl","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a certification (emits TeacherCertificationUpdated)","tags":["Certifications"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"stateCode":{"type":"string","minLength":2,"maxLength":2},"category":{"type":"string","enum":["teaching","administrative","specialist","emergency","substitute","other"]},"certCode":{"type":"string","minLength":1,"maxLength":64},"certLabel":{"type":"string","minLength":1,"maxLength":200},"gradeBands":{"type":"array","items":{"type":"string","maxLength":20},"default":[]},"subjectCodes":{"type":"array","items":{"type":"string","maxLength":20},"default":[]},"certNumber":{"type":"string","maxLength":64},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["active","expired","suspended","revoked","pending"],"default":"active"},"source":{"type":"string","enum":["manual","doe_import","self_report"],"default":"manual"},"documentUrl":{"type":"string","format":"uri","maxLength":500},"notes":{"type":"string","maxLength":500}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"personName":{"type":"string"},"stateCode":{"type":"string","minLength":2,"maxLength":2},"category":{"type":"string","enum":["teaching","administrative","specialist","emergency","substitute","other"]},"certCode":{"type":"string"},"certLabel":{"type":"string"},"gradeBands":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"certNumber":{"type":"string","nullable":true},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["active","expired","suspended","revoked","pending"]},"source":{"type":"string","enum":["manual","doe_import","self_report"]},"documentUrl":{"type":"string","format":"uri","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","personId","stateCode","category","certCode","certLabel","gradeBands","subjectCodes","certNumber","issuedAt","expiresAt","status","source","documentUrl","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/certs/{id}/revoke":{"post":{"summary":"Mark a certification revoked (emits TeacherCertificationRevoked)","tags":["Certifications"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"personName":{"type":"string"},"stateCode":{"type":"string","minLength":2,"maxLength":2},"category":{"type":"string","enum":["teaching","administrative","specialist","emergency","substitute","other"]},"certCode":{"type":"string"},"certLabel":{"type":"string"},"gradeBands":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"certNumber":{"type":"string","nullable":true},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["active","expired","suspended","revoked","pending"]},"source":{"type":"string","enum":["manual","doe_import","self_report"]},"documentUrl":{"type":"string","format":"uri","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","personId","stateCode","category","certCode","certLabel","gradeBands","subjectCodes","certNumber","issuedAt","expiresAt","status","source","documentUrl","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/certs/sweep-expirations":{"post":{"summary":"Sweep expired certs (manual trigger — normally runs on schedule). Emits TeacherCertificationExpired per flipped row.","tags":["Certifications"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"expired":{"type":"integer"},"ids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["expired","ids"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/certs/assignment-check":{"get":{"summary":"Check whether a person holds the certs required for a given role/subject/grade assignment","tags":["Certifications"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"personId","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"query","name":"roleKey","required":true},{"schema":{"type":"string","maxLength":20},"in":"query","name":"subjectCode","required":false},{"schema":{"type":"string","maxLength":20},"in":"query","name":"gradeBand","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eligible":{"type":"boolean"},"matchingCerts":{"type":"array","items":{"type":"object","properties":{"certificationId":{"type":"string","format":"uuid"},"certCode":{"type":"string"},"certLabel":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","nullable":true}},"required":["certificationId","certCode","certLabel","expiresAt"],"additionalProperties":false}},"unmetRequirements":{"type":"array","items":{"type":"object","properties":{"requirementId":{"type":"string","format":"uuid"},"roleKey":{"type":"string"},"allowedCertCodes":{"type":"array","items":{"type":"string"}},"reason":{"type":"string"}},"required":["requirementId","roleKey","allowedCertCodes","reason"],"additionalProperties":false}}},"required":["eligible","matchingCerts","unmetRequirements"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/certs/requirements":{"get":{"summary":"List certification requirement rules","tags":["Certifications"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","maxLength":64},"in":"query","name":"roleKey","required":false},{"schema":{"type":"boolean"},"in":"query","name":"activeOnly","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"roleKey":{"type":"string"},"allowedCertCodes":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"gradeBands":{"type":"array","items":{"type":"string"}},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","roleKey","allowedCertCodes","subjectCodes","gradeBands","description","active","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Add a cert requirement rule (emits CertificationRequirementCreated)","tags":["Certifications"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"roleKey":{"type":"string","minLength":1,"maxLength":64},"allowedCertCodes":{"type":"array","items":{"type":"string","maxLength":64},"default":[]},"subjectCodes":{"type":"array","items":{"type":"string","maxLength":20},"default":[]},"gradeBands":{"type":"array","items":{"type":"string","maxLength":20},"default":[]},"description":{"type":"string","maxLength":500},"active":{"type":"boolean","default":true}},"required":["roleKey"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"roleKey":{"type":"string"},"allowedCertCodes":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"gradeBands":{"type":"array","items":{"type":"string"}},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","roleKey","allowedCertCodes","subjectCodes","gradeBands","description","active","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/certs/requirements/{id}":{"patch":{"summary":"Update a cert requirement rule (emits CertificationRequirementUpdated)","tags":["Certifications"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"roleKey":{"type":"string","minLength":1,"maxLength":64},"allowedCertCodes":{"type":"array","items":{"type":"string","maxLength":64},"default":[]},"subjectCodes":{"type":"array","items":{"type":"string","maxLength":20},"default":[]},"gradeBands":{"type":"array","items":{"type":"string","maxLength":20},"default":[]},"description":{"type":"string","maxLength":500},"active":{"type":"boolean","default":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"roleKey":{"type":"string"},"allowedCertCodes":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"gradeBands":{"type":"array","items":{"type":"string"}},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","roleKey","allowedCertCodes","subjectCodes","gradeBands","description","active","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/certs/requirements/{id}/deactivate":{"post":{"summary":"Deactivate a cert requirement rule (emits CertificationRequirementDeactivated)","tags":["Certifications"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"roleKey":{"type":"string"},"allowedCertCodes":{"type":"array","items":{"type":"string"}},"subjectCodes":{"type":"array","items":{"type":"string"}},"gradeBands":{"type":"array","items":{"type":"string"}},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","roleKey","allowedCertCodes","subjectCodes","gradeBands","description","active","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/facilities/settings":{"get":{"summary":"Get the district facilities settings (SLAs, ticket format, depreciation defaults)","tags":["Facilities"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"districtId":{"type":"string","format":"uuid"},"slaUrgentMinutes":{"type":"integer"},"slaHighMinutes":{"type":"integer"},"slaNormalMinutes":{"type":"integer"},"slaLowMinutes":{"type":"integer"},"ticketNumberFormat":{"type":"string"},"depreciationDefaults":{"type":"object","required":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"],"properties":{"chromebook":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"laptop":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"desktop":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"tablet":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"projector":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"doc_camera":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"printer":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"aed":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"musical_instrument":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"av_other":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"furniture":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"other":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false}},"additionalProperties":false},"persisted":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}},"required":["districtId","slaUrgentMinutes","slaHighMinutes","slaNormalMinutes","slaLowMinutes","ticketNumberFormat","depreciationDefaults","persisted","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update the district facilities settings (emits FacilitiesSettingsUpdated)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"slaUrgentMinutes":{"type":"integer","minimum":5,"maximum":64800},"slaHighMinutes":{"type":"integer","minimum":5,"maximum":64800},"slaNormalMinutes":{"type":"integer","minimum":5,"maximum":64800},"slaLowMinutes":{"type":"integer","minimum":5,"maximum":64800},"ticketNumberFormat":{"type":"string","minLength":6,"maxLength":40,"pattern":"^[A-Z0-9-]+$"},"depreciationDefaults":{"type":"object","required":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"],"properties":{"chromebook":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"laptop":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"desktop":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"tablet":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"projector":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"doc_camera":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"printer":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"aed":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"musical_instrument":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"av_other":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"furniture":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"other":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"districtId":{"type":"string","format":"uuid"},"slaUrgentMinutes":{"type":"integer"},"slaHighMinutes":{"type":"integer"},"slaNormalMinutes":{"type":"integer"},"slaLowMinutes":{"type":"integer"},"ticketNumberFormat":{"type":"string"},"depreciationDefaults":{"type":"object","required":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"],"properties":{"chromebook":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"laptop":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"desktop":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"tablet":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"projector":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"doc_camera":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"printer":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"aed":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"musical_instrument":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"av_other":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"furniture":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false},"other":{"type":"object","properties":{"months":{"type":"integer","minimum":0,"maximum":360},"salvagePct":{"type":"integer","minimum":0,"maximum":100}},"required":["months","salvagePct"],"additionalProperties":false}},"additionalProperties":false},"persisted":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}},"required":["districtId","slaUrgentMinutes","slaHighMinutes","slaNormalMinutes","slaLowMinutes","ticketNumberFormat","depreciationDefaults","persisted","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/rooms":{"get":{"summary":"List rooms (filter by school, type, bookability)","tags":["Facilities"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","enum":["classroom","lab","gym","library","cafeteria","office","nurse","auditorium","storage","restroom","other"]},"in":"query","name":"roomType","required":false},{"schema":{"type":"boolean"},"in":"query","name":"bookableOnly","required":false},{"schema":{"type":"boolean","default":false},"in":"query","name":"includeRetired","required":false},{"schema":{"type":"string","maxLength":100},"in":"query","name":"search","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"number":{"type":"string"},"name":{"type":"string","nullable":true},"roomType":{"type":"string","enum":["classroom","lab","gym","library","cafeteria","office","nurse","auditorium","storage","restroom","other"]},"floor":{"type":"string","nullable":true},"capacity":{"type":"integer","nullable":true},"isBookable":{"type":"boolean"},"notes":{"type":"string","nullable":true},"openWorkOrderCount":{"type":"integer","minimum":0},"assetCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","schoolId","number","name","roomType","floor","capacity","isBookable","notes","createdAt","updatedAt","deletedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a room (emits RoomCreated)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolId":{"type":"string","format":"uuid"},"number":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","maxLength":100},"roomType":{"type":"string","enum":["classroom","lab","gym","library","cafeteria","office","nurse","auditorium","storage","restroom","other"],"default":"classroom"},"floor":{"type":"string","maxLength":30},"capacity":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":5000},"isBookable":{"type":"boolean","default":true},"notes":{"type":"string","maxLength":2000}},"required":["schoolId","number"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"number":{"type":"string"},"name":{"type":"string","nullable":true},"roomType":{"type":"string","enum":["classroom","lab","gym","library","cafeteria","office","nurse","auditorium","storage","restroom","other"]},"floor":{"type":"string","nullable":true},"capacity":{"type":"integer","nullable":true},"isBookable":{"type":"boolean"},"notes":{"type":"string","nullable":true},"openWorkOrderCount":{"type":"integer","minimum":0},"assetCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","schoolId","number","name","roomType","floor","capacity","isBookable","notes","createdAt","updatedAt","deletedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/rooms/{id}":{"get":{"summary":"Get a room","tags":["Facilities"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"number":{"type":"string"},"name":{"type":"string","nullable":true},"roomType":{"type":"string","enum":["classroom","lab","gym","library","cafeteria","office","nurse","auditorium","storage","restroom","other"]},"floor":{"type":"string","nullable":true},"capacity":{"type":"integer","nullable":true},"isBookable":{"type":"boolean"},"notes":{"type":"string","nullable":true},"openWorkOrderCount":{"type":"integer","minimum":0},"assetCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","schoolId","number","name","roomType","floor","capacity","isBookable","notes","createdAt","updatedAt","deletedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Edit a room (emits RoomUpdated when fields change)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","minLength":1,"maxLength":30},"name":{"type":"string","maxLength":100,"nullable":true},"roomType":{"type":"string","enum":["classroom","lab","gym","library","cafeteria","office","nurse","auditorium","storage","restroom","other"]},"floor":{"type":"string","maxLength":30,"nullable":true},"capacity":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":5000,"nullable":true},"isBookable":{"type":"boolean"},"notes":{"type":"string","maxLength":2000,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"number":{"type":"string"},"name":{"type":"string","nullable":true},"roomType":{"type":"string","enum":["classroom","lab","gym","library","cafeteria","office","nurse","auditorium","storage","restroom","other"]},"floor":{"type":"string","nullable":true},"capacity":{"type":"integer","nullable":true},"isBookable":{"type":"boolean"},"notes":{"type":"string","nullable":true},"openWorkOrderCount":{"type":"integer","minimum":0},"assetCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","schoolId","number","name","roomType","floor","capacity","isBookable","notes","createdAt","updatedAt","deletedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/rooms/{id}/retire":{"post":{"summary":"Retire a room (soft-delete, emits RoomRetired)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"number":{"type":"string"},"name":{"type":"string","nullable":true},"roomType":{"type":"string","enum":["classroom","lab","gym","library","cafeteria","office","nurse","auditorium","storage","restroom","other"]},"floor":{"type":"string","nullable":true},"capacity":{"type":"integer","nullable":true},"isBookable":{"type":"boolean"},"notes":{"type":"string","nullable":true},"openWorkOrderCount":{"type":"integer","minimum":0},"assetCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","schoolId","number","name","roomType","floor","capacity","isBookable","notes","createdAt","updatedAt","deletedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/work-orders":{"get":{"summary":"List work orders (board view)","tags":["Facilities"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"roomId","required":false},{"schema":{"type":"string","enum":["open","acknowledged","in_progress","waiting_parts","resolved","closed","cancelled"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["low","normal","high","urgent"]},"in":"query","name":"priority","required":false},{"schema":{"type":"string","enum":["hvac","plumbing","electrical","custodial","grounds","tech","furniture","safety","other"]},"in":"query","name":"category","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"assignedToPersonId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"reportedByUserId","required":false},{"schema":{"type":"boolean"},"in":"query","name":"mine","required":false},{"schema":{"type":"boolean","default":false},"in":"query","name":"openOnly","required":false},{"schema":{"type":"boolean","default":false},"in":"query","name":"overdueOnly","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"ticketNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["hvac","plumbing","electrical","custodial","grounds","tech","furniture","safety","other"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["open","acknowledged","in_progress","waiting_parts","resolved","closed","cancelled"]},"reportedByUserId":{"type":"string","format":"uuid"},"reportedByName":{"type":"string","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"slaDueAt":{"type":"string","format":"date-time","nullable":true},"slaRemainingMinutes":{"type":"integer","nullable":true},"acknowledgedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"resolutionCostCents":{"type":"integer","nullable":true},"resolutionNotes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","roomId","ticketNumber","title","description","category","priority","status","reportedByUserId","reportedByName","assignedToPersonId","assignedToName","slaDueAt","slaRemainingMinutes","acknowledgedAt","resolvedAt","closedAt","cancelledAt","cancelledReason","resolutionCostCents","resolutionNotes","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Open a work order (emits WorkOrderOpened)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":3,"maxLength":200},"description":{"type":"string","minLength":1,"maxLength":5000},"category":{"type":"string","enum":["hvac","plumbing","electrical","custodial","grounds","tech","furniture","safety","other"],"default":"other"},"priority":{"type":"string","enum":["low","normal","high","urgent"],"default":"normal"}},"required":["schoolId","title","description"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"ticketNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["hvac","plumbing","electrical","custodial","grounds","tech","furniture","safety","other"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["open","acknowledged","in_progress","waiting_parts","resolved","closed","cancelled"]},"reportedByUserId":{"type":"string","format":"uuid"},"reportedByName":{"type":"string","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"slaDueAt":{"type":"string","format":"date-time","nullable":true},"slaRemainingMinutes":{"type":"integer","nullable":true},"acknowledgedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"resolutionCostCents":{"type":"integer","nullable":true},"resolutionNotes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["created","assigned","reassigned","status_changed","commented","resolved","closed","cancelled"]},"actorUserId":{"type":"string","format":"uuid","nullable":true},"actorName":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{}},"body":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","kind","actorUserId","actorName","payload","body","createdAt"],"additionalProperties":false}},"roomNumber":{"type":"string","nullable":true},"schoolName":{"type":"string","nullable":true}},"required":["id","districtId","schoolId","roomId","ticketNumber","title","description","category","priority","status","reportedByUserId","reportedByName","assignedToPersonId","assignedToName","slaDueAt","slaRemainingMinutes","acknowledgedAt","resolvedAt","closedAt","cancelledAt","cancelledReason","resolutionCostCents","resolutionNotes","createdAt","updatedAt","events","roomNumber","schoolName"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/work-orders/{id}":{"get":{"summary":"Get a work order with its full event thread","tags":["Facilities"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"ticketNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["hvac","plumbing","electrical","custodial","grounds","tech","furniture","safety","other"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["open","acknowledged","in_progress","waiting_parts","resolved","closed","cancelled"]},"reportedByUserId":{"type":"string","format":"uuid"},"reportedByName":{"type":"string","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"slaDueAt":{"type":"string","format":"date-time","nullable":true},"slaRemainingMinutes":{"type":"integer","nullable":true},"acknowledgedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"resolutionCostCents":{"type":"integer","nullable":true},"resolutionNotes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["created","assigned","reassigned","status_changed","commented","resolved","closed","cancelled"]},"actorUserId":{"type":"string","format":"uuid","nullable":true},"actorName":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{}},"body":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","kind","actorUserId","actorName","payload","body","createdAt"],"additionalProperties":false}},"roomNumber":{"type":"string","nullable":true},"schoolName":{"type":"string","nullable":true}},"required":["id","districtId","schoolId","roomId","ticketNumber","title","description","category","priority","status","reportedByUserId","reportedByName","assignedToPersonId","assignedToName","slaDueAt","slaRemainingMinutes","acknowledgedAt","resolvedAt","closedAt","cancelledAt","cancelledReason","resolutionCostCents","resolutionNotes","createdAt","updatedAt","events","roomNumber","schoolName"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Edit a work order (title / description / category / priority / room / SLA)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":200},"description":{"type":"string","minLength":1,"maxLength":5000},"category":{"type":"string","enum":["hvac","plumbing","electrical","custodial","grounds","tech","furniture","safety","other"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"roomId":{"type":"string","format":"uuid","nullable":true},"slaDueAt":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"ticketNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["hvac","plumbing","electrical","custodial","grounds","tech","furniture","safety","other"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["open","acknowledged","in_progress","waiting_parts","resolved","closed","cancelled"]},"reportedByUserId":{"type":"string","format":"uuid"},"reportedByName":{"type":"string","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"slaDueAt":{"type":"string","format":"date-time","nullable":true},"slaRemainingMinutes":{"type":"integer","nullable":true},"acknowledgedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"resolutionCostCents":{"type":"integer","nullable":true},"resolutionNotes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["created","assigned","reassigned","status_changed","commented","resolved","closed","cancelled"]},"actorUserId":{"type":"string","format":"uuid","nullable":true},"actorName":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{}},"body":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","kind","actorUserId","actorName","payload","body","createdAt"],"additionalProperties":false}},"roomNumber":{"type":"string","nullable":true},"schoolName":{"type":"string","nullable":true}},"required":["id","districtId","schoolId","roomId","ticketNumber","title","description","category","priority","status","reportedByUserId","reportedByName","assignedToPersonId","assignedToName","slaDueAt","slaRemainingMinutes","acknowledgedAt","resolvedAt","closedAt","cancelledAt","cancelledReason","resolutionCostCents","resolutionNotes","createdAt","updatedAt","events","roomNumber","schoolName"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/work-orders/{id}/assign":{"post":{"summary":"Assign or reassign the ticket (emits WorkOrderAssigned)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignedToPersonId":{"type":"string","format":"uuid","nullable":true}},"required":["assignedToPersonId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"ticketNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["hvac","plumbing","electrical","custodial","grounds","tech","furniture","safety","other"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["open","acknowledged","in_progress","waiting_parts","resolved","closed","cancelled"]},"reportedByUserId":{"type":"string","format":"uuid"},"reportedByName":{"type":"string","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"slaDueAt":{"type":"string","format":"date-time","nullable":true},"slaRemainingMinutes":{"type":"integer","nullable":true},"acknowledgedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"resolutionCostCents":{"type":"integer","nullable":true},"resolutionNotes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["created","assigned","reassigned","status_changed","commented","resolved","closed","cancelled"]},"actorUserId":{"type":"string","format":"uuid","nullable":true},"actorName":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{}},"body":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","kind","actorUserId","actorName","payload","body","createdAt"],"additionalProperties":false}},"roomNumber":{"type":"string","nullable":true},"schoolName":{"type":"string","nullable":true}},"required":["id","districtId","schoolId","roomId","ticketNumber","title","description","category","priority","status","reportedByUserId","reportedByName","assignedToPersonId","assignedToName","slaDueAt","slaRemainingMinutes","acknowledgedAt","resolvedAt","closedAt","cancelledAt","cancelledReason","resolutionCostCents","resolutionNotes","createdAt","updatedAt","events","roomNumber","schoolName"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/work-orders/{id}/status":{"post":{"summary":"Transition ticket status (emits WorkOrderStatusChanged)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","acknowledged","in_progress","waiting_parts","resolved","closed","cancelled"]}},"required":["status"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"ticketNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["hvac","plumbing","electrical","custodial","grounds","tech","furniture","safety","other"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["open","acknowledged","in_progress","waiting_parts","resolved","closed","cancelled"]},"reportedByUserId":{"type":"string","format":"uuid"},"reportedByName":{"type":"string","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"slaDueAt":{"type":"string","format":"date-time","nullable":true},"slaRemainingMinutes":{"type":"integer","nullable":true},"acknowledgedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"resolutionCostCents":{"type":"integer","nullable":true},"resolutionNotes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["created","assigned","reassigned","status_changed","commented","resolved","closed","cancelled"]},"actorUserId":{"type":"string","format":"uuid","nullable":true},"actorName":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{}},"body":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","kind","actorUserId","actorName","payload","body","createdAt"],"additionalProperties":false}},"roomNumber":{"type":"string","nullable":true},"schoolName":{"type":"string","nullable":true}},"required":["id","districtId","schoolId","roomId","ticketNumber","title","description","category","priority","status","reportedByUserId","reportedByName","assignedToPersonId","assignedToName","slaDueAt","slaRemainingMinutes","acknowledgedAt","resolvedAt","closedAt","cancelledAt","cancelledReason","resolutionCostCents","resolutionNotes","createdAt","updatedAt","events","roomNumber","schoolName"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/work-orders/{id}/comments":{"post":{"summary":"Comment on a work-order thread (emits WorkOrderCommented)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":5000}},"required":["body"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"ticketNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["hvac","plumbing","electrical","custodial","grounds","tech","furniture","safety","other"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["open","acknowledged","in_progress","waiting_parts","resolved","closed","cancelled"]},"reportedByUserId":{"type":"string","format":"uuid"},"reportedByName":{"type":"string","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"slaDueAt":{"type":"string","format":"date-time","nullable":true},"slaRemainingMinutes":{"type":"integer","nullable":true},"acknowledgedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"resolutionCostCents":{"type":"integer","nullable":true},"resolutionNotes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["created","assigned","reassigned","status_changed","commented","resolved","closed","cancelled"]},"actorUserId":{"type":"string","format":"uuid","nullable":true},"actorName":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{}},"body":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","kind","actorUserId","actorName","payload","body","createdAt"],"additionalProperties":false}},"roomNumber":{"type":"string","nullable":true},"schoolName":{"type":"string","nullable":true}},"required":["id","districtId","schoolId","roomId","ticketNumber","title","description","category","priority","status","reportedByUserId","reportedByName","assignedToPersonId","assignedToName","slaDueAt","slaRemainingMinutes","acknowledgedAt","resolvedAt","closedAt","cancelledAt","cancelledReason","resolutionCostCents","resolutionNotes","createdAt","updatedAt","events","roomNumber","schoolName"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/work-orders/{id}/resolve":{"post":{"summary":"Resolve a work order (emits WorkOrderResolved)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolutionNotes":{"type":"string","minLength":1,"maxLength":5000},"resolutionCostCents":{"type":"integer","minimum":0,"maximum":100000000}},"required":["resolutionNotes"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"ticketNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["hvac","plumbing","electrical","custodial","grounds","tech","furniture","safety","other"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["open","acknowledged","in_progress","waiting_parts","resolved","closed","cancelled"]},"reportedByUserId":{"type":"string","format":"uuid"},"reportedByName":{"type":"string","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"slaDueAt":{"type":"string","format":"date-time","nullable":true},"slaRemainingMinutes":{"type":"integer","nullable":true},"acknowledgedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"resolutionCostCents":{"type":"integer","nullable":true},"resolutionNotes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["created","assigned","reassigned","status_changed","commented","resolved","closed","cancelled"]},"actorUserId":{"type":"string","format":"uuid","nullable":true},"actorName":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{}},"body":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","kind","actorUserId","actorName","payload","body","createdAt"],"additionalProperties":false}},"roomNumber":{"type":"string","nullable":true},"schoolName":{"type":"string","nullable":true}},"required":["id","districtId","schoolId","roomId","ticketNumber","title","description","category","priority","status","reportedByUserId","reportedByName","assignedToPersonId","assignedToName","slaDueAt","slaRemainingMinutes","acknowledgedAt","resolvedAt","closedAt","cancelledAt","cancelledReason","resolutionCostCents","resolutionNotes","createdAt","updatedAt","events","roomNumber","schoolName"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/work-orders/{id}/cancel":{"post":{"summary":"Cancel a work order (emits WorkOrderCancelled)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"ticketNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["hvac","plumbing","electrical","custodial","grounds","tech","furniture","safety","other"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"status":{"type":"string","enum":["open","acknowledged","in_progress","waiting_parts","resolved","closed","cancelled"]},"reportedByUserId":{"type":"string","format":"uuid"},"reportedByName":{"type":"string","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"slaDueAt":{"type":"string","format":"date-time","nullable":true},"slaRemainingMinutes":{"type":"integer","nullable":true},"acknowledgedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"resolutionCostCents":{"type":"integer","nullable":true},"resolutionNotes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["created","assigned","reassigned","status_changed","commented","resolved","closed","cancelled"]},"actorUserId":{"type":"string","format":"uuid","nullable":true},"actorName":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{}},"body":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","kind","actorUserId","actorName","payload","body","createdAt"],"additionalProperties":false}},"roomNumber":{"type":"string","nullable":true},"schoolName":{"type":"string","nullable":true}},"required":["id","districtId","schoolId","roomId","ticketNumber","title","description","category","priority","status","reportedByUserId","reportedByName","assignedToPersonId","assignedToName","slaDueAt","slaRemainingMinutes","acknowledgedAt","resolvedAt","closedAt","cancelledAt","cancelledReason","resolutionCostCents","resolutionNotes","createdAt","updatedAt","events","roomNumber","schoolName"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assets":{"get":{"summary":"List assets","tags":["Facilities"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"roomId","required":false},{"schema":{"type":"string","enum":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"]},"in":"query","name":"category","required":false},{"schema":{"type":"string","enum":["active","in_repair","retired","lost","stolen"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"assignedToPersonId","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search","required":false},{"schema":{"type":"boolean","default":false},"in":"query","name":"includeRetired","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"tag":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"]},"manufacturer":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"serialNumber":{"type":"string","nullable":true},"acquiredOn":{"type":"string","format":"date","nullable":true},"purchaseCostCents":{"type":"integer","nullable":true},"condition":{"type":"string","enum":["new","good","fair","poor","broken","retired","lost","stolen"]},"status":{"type":"string","enum":["active","in_repair","retired","lost","stolen"]},"depreciationMethod":{"type":"string","enum":["straight_line","none"]},"depreciationStartDate":{"type":"string","format":"date","nullable":true},"usefulLifeMonths":{"type":"integer","nullable":true},"salvageValueCents":{"type":"integer","nullable":true},"currentBookValueCents":{"type":"integer","nullable":true},"bookValueAsOf":{"type":"string","format":"date-time","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"assignedAt":{"type":"string","format":"date-time","nullable":true},"warrantyExpiresOn":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true},"roomNumber":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","schoolId","roomId","tag","name","category","manufacturer","model","serialNumber","acquiredOn","purchaseCostCents","condition","status","depreciationMethod","depreciationStartDate","usefulLifeMonths","salvageValueCents","currentBookValueCents","bookValueAsOf","assignedToPersonId","assignedToName","assignedAt","warrantyExpiresOn","notes","roomNumber","createdAt","updatedAt","deletedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Register a new asset (emits AssetRegistered)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid"},"tag":{"type":"string","minLength":1,"maxLength":40},"name":{"type":"string","minLength":1,"maxLength":200},"category":{"type":"string","enum":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"],"default":"other"},"manufacturer":{"type":"string","maxLength":100},"model":{"type":"string","maxLength":100},"serialNumber":{"type":"string","maxLength":100},"acquiredOn":{"type":"string","format":"date"},"purchaseCostCents":{"type":"integer","minimum":0,"maximum":1000000000},"condition":{"type":"string","enum":["new","good","fair","poor","broken","retired","lost","stolen"],"default":"good"},"depreciationMethod":{"type":"string","enum":["straight_line","none"],"default":"none"},"depreciationStartDate":{"type":"string","format":"date"},"usefulLifeMonths":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":360},"salvageValueCents":{"type":"integer","minimum":0,"maximum":1000000000},"warrantyExpiresOn":{"type":"string","format":"date"},"notes":{"type":"string","maxLength":2000}},"required":["schoolId","tag","name"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"tag":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"]},"manufacturer":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"serialNumber":{"type":"string","nullable":true},"acquiredOn":{"type":"string","format":"date","nullable":true},"purchaseCostCents":{"type":"integer","nullable":true},"condition":{"type":"string","enum":["new","good","fair","poor","broken","retired","lost","stolen"]},"status":{"type":"string","enum":["active","in_repair","retired","lost","stolen"]},"depreciationMethod":{"type":"string","enum":["straight_line","none"]},"depreciationStartDate":{"type":"string","format":"date","nullable":true},"usefulLifeMonths":{"type":"integer","nullable":true},"salvageValueCents":{"type":"integer","nullable":true},"currentBookValueCents":{"type":"integer","nullable":true},"bookValueAsOf":{"type":"string","format":"date-time","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"assignedAt":{"type":"string","format":"date-time","nullable":true},"warrantyExpiresOn":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true},"roomNumber":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true},"adjustments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deltaCents":{"type":"integer"},"reasonCode":{"type":"string","enum":["write_down","revaluation","repair_capitalized","correction","other"]},"reason":{"type":"string"},"newBookValueCents":{"type":"integer","minimum":0},"appliedOn":{"type":"string","format":"date"},"recordedByUserId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","deltaCents","reasonCode","reason","newBookValueCents","appliedOn","recordedByUserId","createdAt"],"additionalProperties":false}}},"required":["id","districtId","schoolId","roomId","tag","name","category","manufacturer","model","serialNumber","acquiredOn","purchaseCostCents","condition","status","depreciationMethod","depreciationStartDate","usefulLifeMonths","salvageValueCents","currentBookValueCents","bookValueAsOf","assignedToPersonId","assignedToName","assignedAt","warrantyExpiresOn","notes","roomNumber","createdAt","updatedAt","deletedAt","adjustments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assets/reports/depreciation":{"get":{"summary":"Roll-up of book value by asset category","tags":["Facilities"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"schoolId":{"type":"string","format":"uuid","nullable":true},"rows":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","enum":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"]},"assetCount":{"type":"integer","minimum":0},"totalPurchaseCents":{"type":"integer","minimum":0},"totalBookValueCents":{"type":"integer","minimum":0},"depreciatedCents":{"type":"integer"}},"required":["category","assetCount","totalPurchaseCents","totalBookValueCents","depreciatedCents"],"additionalProperties":false}},"totals":{"type":"object","properties":{"assetCount":{"type":"integer","minimum":0},"totalPurchaseCents":{"type":"integer","minimum":0},"totalBookValueCents":{"type":"integer","minimum":0},"depreciatedCents":{"type":"integer"}},"required":["assetCount","totalPurchaseCents","totalBookValueCents","depreciatedCents"],"additionalProperties":false}},"required":["asOf","schoolId","rows","totals"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assets/{id}":{"get":{"summary":"Get an asset with its adjustment history","tags":["Facilities"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"tag":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"]},"manufacturer":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"serialNumber":{"type":"string","nullable":true},"acquiredOn":{"type":"string","format":"date","nullable":true},"purchaseCostCents":{"type":"integer","nullable":true},"condition":{"type":"string","enum":["new","good","fair","poor","broken","retired","lost","stolen"]},"status":{"type":"string","enum":["active","in_repair","retired","lost","stolen"]},"depreciationMethod":{"type":"string","enum":["straight_line","none"]},"depreciationStartDate":{"type":"string","format":"date","nullable":true},"usefulLifeMonths":{"type":"integer","nullable":true},"salvageValueCents":{"type":"integer","nullable":true},"currentBookValueCents":{"type":"integer","nullable":true},"bookValueAsOf":{"type":"string","format":"date-time","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"assignedAt":{"type":"string","format":"date-time","nullable":true},"warrantyExpiresOn":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true},"roomNumber":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true},"adjustments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deltaCents":{"type":"integer"},"reasonCode":{"type":"string","enum":["write_down","revaluation","repair_capitalized","correction","other"]},"reason":{"type":"string"},"newBookValueCents":{"type":"integer","minimum":0},"appliedOn":{"type":"string","format":"date"},"recordedByUserId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","deltaCents","reasonCode","reason","newBookValueCents","appliedOn","recordedByUserId","createdAt"],"additionalProperties":false}}},"required":["id","districtId","schoolId","roomId","tag","name","category","manufacturer","model","serialNumber","acquiredOn","purchaseCostCents","condition","status","depreciationMethod","depreciationStartDate","usefulLifeMonths","salvageValueCents","currentBookValueCents","bookValueAsOf","assignedToPersonId","assignedToName","assignedAt","warrantyExpiresOn","notes","roomNumber","createdAt","updatedAt","deletedAt","adjustments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Edit an asset","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"manufacturer":{"type":"string","maxLength":100,"nullable":true},"model":{"type":"string","maxLength":100,"nullable":true},"serialNumber":{"type":"string","maxLength":100,"nullable":true},"purchaseCostCents":{"type":"integer","minimum":0,"maximum":1000000000,"nullable":true},"condition":{"type":"string","enum":["new","good","fair","poor","broken","retired","lost","stolen"]},"depreciationMethod":{"type":"string","enum":["straight_line","none"]},"depreciationStartDate":{"type":"string","format":"date","nullable":true},"usefulLifeMonths":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":360,"nullable":true},"salvageValueCents":{"type":"integer","minimum":0,"maximum":1000000000,"nullable":true},"warrantyExpiresOn":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","maxLength":2000,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"tag":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"]},"manufacturer":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"serialNumber":{"type":"string","nullable":true},"acquiredOn":{"type":"string","format":"date","nullable":true},"purchaseCostCents":{"type":"integer","nullable":true},"condition":{"type":"string","enum":["new","good","fair","poor","broken","retired","lost","stolen"]},"status":{"type":"string","enum":["active","in_repair","retired","lost","stolen"]},"depreciationMethod":{"type":"string","enum":["straight_line","none"]},"depreciationStartDate":{"type":"string","format":"date","nullable":true},"usefulLifeMonths":{"type":"integer","nullable":true},"salvageValueCents":{"type":"integer","nullable":true},"currentBookValueCents":{"type":"integer","nullable":true},"bookValueAsOf":{"type":"string","format":"date-time","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"assignedAt":{"type":"string","format":"date-time","nullable":true},"warrantyExpiresOn":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true},"roomNumber":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true},"adjustments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deltaCents":{"type":"integer"},"reasonCode":{"type":"string","enum":["write_down","revaluation","repair_capitalized","correction","other"]},"reason":{"type":"string"},"newBookValueCents":{"type":"integer","minimum":0},"appliedOn":{"type":"string","format":"date"},"recordedByUserId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","deltaCents","reasonCode","reason","newBookValueCents","appliedOn","recordedByUserId","createdAt"],"additionalProperties":false}}},"required":["id","districtId","schoolId","roomId","tag","name","category","manufacturer","model","serialNumber","acquiredOn","purchaseCostCents","condition","status","depreciationMethod","depreciationStartDate","usefulLifeMonths","salvageValueCents","currentBookValueCents","bookValueAsOf","assignedToPersonId","assignedToName","assignedAt","warrantyExpiresOn","notes","roomNumber","createdAt","updatedAt","deletedAt","adjustments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assets/{id}/move":{"post":{"summary":"Move an asset between rooms (emits AssetMoved)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"toRoomId":{"type":"string","format":"uuid","nullable":true}},"required":["toRoomId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"tag":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"]},"manufacturer":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"serialNumber":{"type":"string","nullable":true},"acquiredOn":{"type":"string","format":"date","nullable":true},"purchaseCostCents":{"type":"integer","nullable":true},"condition":{"type":"string","enum":["new","good","fair","poor","broken","retired","lost","stolen"]},"status":{"type":"string","enum":["active","in_repair","retired","lost","stolen"]},"depreciationMethod":{"type":"string","enum":["straight_line","none"]},"depreciationStartDate":{"type":"string","format":"date","nullable":true},"usefulLifeMonths":{"type":"integer","nullable":true},"salvageValueCents":{"type":"integer","nullable":true},"currentBookValueCents":{"type":"integer","nullable":true},"bookValueAsOf":{"type":"string","format":"date-time","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"assignedAt":{"type":"string","format":"date-time","nullable":true},"warrantyExpiresOn":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true},"roomNumber":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true},"adjustments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deltaCents":{"type":"integer"},"reasonCode":{"type":"string","enum":["write_down","revaluation","repair_capitalized","correction","other"]},"reason":{"type":"string"},"newBookValueCents":{"type":"integer","minimum":0},"appliedOn":{"type":"string","format":"date"},"recordedByUserId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","deltaCents","reasonCode","reason","newBookValueCents","appliedOn","recordedByUserId","createdAt"],"additionalProperties":false}}},"required":["id","districtId","schoolId","roomId","tag","name","category","manufacturer","model","serialNumber","acquiredOn","purchaseCostCents","condition","status","depreciationMethod","depreciationStartDate","usefulLifeMonths","salvageValueCents","currentBookValueCents","bookValueAsOf","assignedToPersonId","assignedToName","assignedAt","warrantyExpiresOn","notes","roomNumber","createdAt","updatedAt","deletedAt","adjustments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assets/{id}/assign":{"post":{"summary":"Assign / unassign custody of an asset (emits AssetAssigned)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"toPersonId":{"type":"string","format":"uuid","nullable":true}},"required":["toPersonId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"tag":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"]},"manufacturer":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"serialNumber":{"type":"string","nullable":true},"acquiredOn":{"type":"string","format":"date","nullable":true},"purchaseCostCents":{"type":"integer","nullable":true},"condition":{"type":"string","enum":["new","good","fair","poor","broken","retired","lost","stolen"]},"status":{"type":"string","enum":["active","in_repair","retired","lost","stolen"]},"depreciationMethod":{"type":"string","enum":["straight_line","none"]},"depreciationStartDate":{"type":"string","format":"date","nullable":true},"usefulLifeMonths":{"type":"integer","nullable":true},"salvageValueCents":{"type":"integer","nullable":true},"currentBookValueCents":{"type":"integer","nullable":true},"bookValueAsOf":{"type":"string","format":"date-time","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"assignedAt":{"type":"string","format":"date-time","nullable":true},"warrantyExpiresOn":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true},"roomNumber":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true},"adjustments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deltaCents":{"type":"integer"},"reasonCode":{"type":"string","enum":["write_down","revaluation","repair_capitalized","correction","other"]},"reason":{"type":"string"},"newBookValueCents":{"type":"integer","minimum":0},"appliedOn":{"type":"string","format":"date"},"recordedByUserId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","deltaCents","reasonCode","reason","newBookValueCents","appliedOn","recordedByUserId","createdAt"],"additionalProperties":false}}},"required":["id","districtId","schoolId","roomId","tag","name","category","manufacturer","model","serialNumber","acquiredOn","purchaseCostCents","condition","status","depreciationMethod","depreciationStartDate","usefulLifeMonths","salvageValueCents","currentBookValueCents","bookValueAsOf","assignedToPersonId","assignedToName","assignedAt","warrantyExpiresOn","notes","roomNumber","createdAt","updatedAt","deletedAt","adjustments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assets/{id}/status":{"post":{"summary":"Change asset status (emits AssetStatusChanged)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","in_repair","retired","lost","stolen"]},"reason":{"type":"string","maxLength":500}},"required":["status"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"tag":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"]},"manufacturer":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"serialNumber":{"type":"string","nullable":true},"acquiredOn":{"type":"string","format":"date","nullable":true},"purchaseCostCents":{"type":"integer","nullable":true},"condition":{"type":"string","enum":["new","good","fair","poor","broken","retired","lost","stolen"]},"status":{"type":"string","enum":["active","in_repair","retired","lost","stolen"]},"depreciationMethod":{"type":"string","enum":["straight_line","none"]},"depreciationStartDate":{"type":"string","format":"date","nullable":true},"usefulLifeMonths":{"type":"integer","nullable":true},"salvageValueCents":{"type":"integer","nullable":true},"currentBookValueCents":{"type":"integer","nullable":true},"bookValueAsOf":{"type":"string","format":"date-time","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"assignedAt":{"type":"string","format":"date-time","nullable":true},"warrantyExpiresOn":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true},"roomNumber":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true},"adjustments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deltaCents":{"type":"integer"},"reasonCode":{"type":"string","enum":["write_down","revaluation","repair_capitalized","correction","other"]},"reason":{"type":"string"},"newBookValueCents":{"type":"integer","minimum":0},"appliedOn":{"type":"string","format":"date"},"recordedByUserId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","deltaCents","reasonCode","reason","newBookValueCents","appliedOn","recordedByUserId","createdAt"],"additionalProperties":false}}},"required":["id","districtId","schoolId","roomId","tag","name","category","manufacturer","model","serialNumber","acquiredOn","purchaseCostCents","condition","status","depreciationMethod","depreciationStartDate","usefulLifeMonths","salvageValueCents","currentBookValueCents","bookValueAsOf","assignedToPersonId","assignedToName","assignedAt","warrantyExpiresOn","notes","roomNumber","createdAt","updatedAt","deletedAt","adjustments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assets/{id}/revalue":{"post":{"summary":"Apply a valuation adjustment (write-down, revaluation, etc.)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"deltaCents":{"type":"integer"},"reasonCode":{"type":"string","enum":["write_down","revaluation","repair_capitalized","correction","other"]},"reason":{"type":"string","minLength":1,"maxLength":2000},"appliedOn":{"type":"string","format":"date"}},"required":["deltaCents","reasonCode","reason","appliedOn"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"tag":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"]},"manufacturer":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"serialNumber":{"type":"string","nullable":true},"acquiredOn":{"type":"string","format":"date","nullable":true},"purchaseCostCents":{"type":"integer","nullable":true},"condition":{"type":"string","enum":["new","good","fair","poor","broken","retired","lost","stolen"]},"status":{"type":"string","enum":["active","in_repair","retired","lost","stolen"]},"depreciationMethod":{"type":"string","enum":["straight_line","none"]},"depreciationStartDate":{"type":"string","format":"date","nullable":true},"usefulLifeMonths":{"type":"integer","nullable":true},"salvageValueCents":{"type":"integer","nullable":true},"currentBookValueCents":{"type":"integer","nullable":true},"bookValueAsOf":{"type":"string","format":"date-time","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"assignedAt":{"type":"string","format":"date-time","nullable":true},"warrantyExpiresOn":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true},"roomNumber":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true},"adjustments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deltaCents":{"type":"integer"},"reasonCode":{"type":"string","enum":["write_down","revaluation","repair_capitalized","correction","other"]},"reason":{"type":"string"},"newBookValueCents":{"type":"integer","minimum":0},"appliedOn":{"type":"string","format":"date"},"recordedByUserId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","deltaCents","reasonCode","reason","newBookValueCents","appliedOn","recordedByUserId","createdAt"],"additionalProperties":false}}},"required":["id","districtId","schoolId","roomId","tag","name","category","manufacturer","model","serialNumber","acquiredOn","purchaseCostCents","condition","status","depreciationMethod","depreciationStartDate","usefulLifeMonths","salvageValueCents","currentBookValueCents","bookValueAsOf","assignedToPersonId","assignedToName","assignedAt","warrantyExpiresOn","notes","roomNumber","createdAt","updatedAt","deletedAt","adjustments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assets/{id}/retire":{"post":{"summary":"Retire an asset (soft-delete, emits AssetRetired)","tags":["Facilities"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"roomId":{"type":"string","format":"uuid","nullable":true},"tag":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["chromebook","laptop","desktop","tablet","projector","doc_camera","printer","aed","musical_instrument","av_other","furniture","other"]},"manufacturer":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"serialNumber":{"type":"string","nullable":true},"acquiredOn":{"type":"string","format":"date","nullable":true},"purchaseCostCents":{"type":"integer","nullable":true},"condition":{"type":"string","enum":["new","good","fair","poor","broken","retired","lost","stolen"]},"status":{"type":"string","enum":["active","in_repair","retired","lost","stolen"]},"depreciationMethod":{"type":"string","enum":["straight_line","none"]},"depreciationStartDate":{"type":"string","format":"date","nullable":true},"usefulLifeMonths":{"type":"integer","nullable":true},"salvageValueCents":{"type":"integer","nullable":true},"currentBookValueCents":{"type":"integer","nullable":true},"bookValueAsOf":{"type":"string","format":"date-time","nullable":true},"assignedToPersonId":{"type":"string","format":"uuid","nullable":true},"assignedToName":{"type":"string","nullable":true},"assignedAt":{"type":"string","format":"date-time","nullable":true},"warrantyExpiresOn":{"type":"string","format":"date","nullable":true},"notes":{"type":"string","nullable":true},"roomNumber":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true},"adjustments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deltaCents":{"type":"integer"},"reasonCode":{"type":"string","enum":["write_down","revaluation","repair_capitalized","correction","other"]},"reason":{"type":"string"},"newBookValueCents":{"type":"integer","minimum":0},"appliedOn":{"type":"string","format":"date"},"recordedByUserId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","deltaCents","reasonCode","reason","newBookValueCents","appliedOn","recordedByUserId","createdAt"],"additionalProperties":false}}},"required":["id","districtId","schoolId","roomId","tag","name","category","manufacturer","model","serialNumber","acquiredOn","purchaseCostCents","condition","status","depreciationMethod","depreciationStartDate","usefulLifeMonths","salvageValueCents","currentBookValueCents","bookValueAsOf","assignedToPersonId","assignedToName","assignedAt","warrantyExpiresOn","notes","roomNumber","createdAt","updatedAt","deletedAt","adjustments"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/safety-drills":{"get":{"summary":"List safety drills","tags":["Safety"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":false},{"schema":{"type":"string","enum":["fire","lockdown","shelter_in_place","evacuation","bus_evacuation","severe_weather","bomb_threat","other"]},"in":"query","name":"drillType","required":false},{"schema":{"type":"boolean"},"in":"query","name":"publicVisibleOnly","required":false},{"schema":{"type":"boolean"},"in":"query","name":"unreportedOnly","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"drillType":{"type":"string","enum":["fire","lockdown","shelter_in_place","evacuation","bus_evacuation","severe_weather","bomb_threat","other"]},"drillDate":{"type":"string","format":"date"},"startTime":{"type":"string"},"durationSeconds":{"type":"integer","nullable":true},"wasAnnounced":{"type":"boolean"},"participantCount":{"type":"integer","nullable":true},"conductedByPersonId":{"type":"string","format":"uuid","nullable":true},"conductedByName":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"publicVisible":{"type":"boolean"},"externallyReportedAt":{"type":"string","format":"date-time","nullable":true},"externalReportRef":{"type":"string","nullable":true},"stateReportCategory":{"type":"string","enum":["fire","non_fire_security","bus_evacuation","other"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","schoolId","schoolYearId","drillType","drillDate","startTime","durationSeconds","wasAnnounced","participantCount","conductedByPersonId","conductedByName","notes","publicVisible","externallyReportedAt","externalReportRef","stateReportCategory","createdAt","updatedAt","deletedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Log a new safety drill (emits SafetyDrillLogged)","tags":["Safety"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"drillType":{"type":"string","enum":["fire","lockdown","shelter_in_place","evacuation","bus_evacuation","severe_weather","bomb_threat","other"]},"drillDate":{"type":"string","format":"date"},"startTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"durationSeconds":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":14400},"wasAnnounced":{"type":"boolean","default":true},"participantCount":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":20000},"conductedByPersonId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":2000},"publicVisible":{"type":"boolean","default":false},"stateReportCategory":{"type":"string","enum":["fire","non_fire_security","bus_evacuation","other"]}},"required":["schoolId","schoolYearId","drillType","drillDate","startTime"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"drillType":{"type":"string","enum":["fire","lockdown","shelter_in_place","evacuation","bus_evacuation","severe_weather","bomb_threat","other"]},"drillDate":{"type":"string","format":"date"},"startTime":{"type":"string"},"durationSeconds":{"type":"integer","nullable":true},"wasAnnounced":{"type":"boolean"},"participantCount":{"type":"integer","nullable":true},"conductedByPersonId":{"type":"string","format":"uuid","nullable":true},"conductedByName":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"publicVisible":{"type":"boolean"},"externallyReportedAt":{"type":"string","format":"date-time","nullable":true},"externalReportRef":{"type":"string","nullable":true},"stateReportCategory":{"type":"string","enum":["fire","non_fire_security","bus_evacuation","other"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","schoolId","schoolYearId","drillType","drillDate","startTime","durationSeconds","wasAnnounced","participantCount","conductedByPersonId","conductedByName","notes","publicVisible","externallyReportedAt","externalReportRef","stateReportCategory","createdAt","updatedAt","deletedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/safety-drills/annual-report":{"get":{"summary":"Annual state-report roll-up (NJ category counts per school)","tags":["Safety"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"rows":{"type":"array","items":{"type":"object","properties":{"schoolId":{"type":"string","format":"uuid"},"schoolName":{"type":"string"},"totals":{"type":"object","properties":{"fire":{"type":"integer","minimum":0},"non_fire_security":{"type":"integer","minimum":0},"bus_evacuation":{"type":"integer","minimum":0},"other":{"type":"integer","minimum":0},"announced":{"type":"integer","minimum":0},"unannounced":{"type":"integer","minimum":0},"pendingReport":{"type":"integer","minimum":0}},"required":["fire","non_fire_security","bus_evacuation","other","announced","unannounced","pendingReport"],"additionalProperties":false}},"required":["schoolId","schoolName","totals"],"additionalProperties":false}}},"required":["schoolYearId","rows"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/safety-drills/{id}":{"get":{"summary":"Get a safety drill","tags":["Safety"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"drillType":{"type":"string","enum":["fire","lockdown","shelter_in_place","evacuation","bus_evacuation","severe_weather","bomb_threat","other"]},"drillDate":{"type":"string","format":"date"},"startTime":{"type":"string"},"durationSeconds":{"type":"integer","nullable":true},"wasAnnounced":{"type":"boolean"},"participantCount":{"type":"integer","nullable":true},"conductedByPersonId":{"type":"string","format":"uuid","nullable":true},"conductedByName":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"publicVisible":{"type":"boolean"},"externallyReportedAt":{"type":"string","format":"date-time","nullable":true},"externalReportRef":{"type":"string","nullable":true},"stateReportCategory":{"type":"string","enum":["fire","non_fire_security","bus_evacuation","other"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","schoolId","schoolYearId","drillType","drillDate","startTime","durationSeconds","wasAnnounced","participantCount","conductedByPersonId","conductedByName","notes","publicVisible","externallyReportedAt","externalReportRef","stateReportCategory","createdAt","updatedAt","deletedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Correct a drill entry (emits SafetyDrillCorrected when fields change)","tags":["Safety"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"drillType":{"type":"string","enum":["fire","lockdown","shelter_in_place","evacuation","bus_evacuation","severe_weather","bomb_threat","other"]},"drillDate":{"type":"string","format":"date"},"startTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"durationSeconds":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":14400,"nullable":true},"wasAnnounced":{"type":"boolean"},"participantCount":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":20000,"nullable":true},"conductedByPersonId":{"type":"string","format":"uuid","nullable":true},"notes":{"type":"string","maxLength":2000,"nullable":true},"stateReportCategory":{"type":"string","enum":["fire","non_fire_security","bus_evacuation","other"]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"drillType":{"type":"string","enum":["fire","lockdown","shelter_in_place","evacuation","bus_evacuation","severe_weather","bomb_threat","other"]},"drillDate":{"type":"string","format":"date"},"startTime":{"type":"string"},"durationSeconds":{"type":"integer","nullable":true},"wasAnnounced":{"type":"boolean"},"participantCount":{"type":"integer","nullable":true},"conductedByPersonId":{"type":"string","format":"uuid","nullable":true},"conductedByName":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"publicVisible":{"type":"boolean"},"externallyReportedAt":{"type":"string","format":"date-time","nullable":true},"externalReportRef":{"type":"string","nullable":true},"stateReportCategory":{"type":"string","enum":["fire","non_fire_security","bus_evacuation","other"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","schoolId","schoolYearId","drillType","drillDate","startTime","durationSeconds","wasAnnounced","participantCount","conductedByPersonId","conductedByName","notes","publicVisible","externallyReportedAt","externalReportRef","stateReportCategory","createdAt","updatedAt","deletedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/safety-drills/{id}/visibility":{"post":{"summary":"Toggle public (parent-page) visibility (emits SafetyDrillVisibilityChanged)","tags":["Safety"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"publicVisible":{"type":"boolean"}},"required":["publicVisible"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"drillType":{"type":"string","enum":["fire","lockdown","shelter_in_place","evacuation","bus_evacuation","severe_weather","bomb_threat","other"]},"drillDate":{"type":"string","format":"date"},"startTime":{"type":"string"},"durationSeconds":{"type":"integer","nullable":true},"wasAnnounced":{"type":"boolean"},"participantCount":{"type":"integer","nullable":true},"conductedByPersonId":{"type":"string","format":"uuid","nullable":true},"conductedByName":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"publicVisible":{"type":"boolean"},"externallyReportedAt":{"type":"string","format":"date-time","nullable":true},"externalReportRef":{"type":"string","nullable":true},"stateReportCategory":{"type":"string","enum":["fire","non_fire_security","bus_evacuation","other"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","schoolId","schoolYearId","drillType","drillDate","startTime","durationSeconds","wasAnnounced","participantCount","conductedByPersonId","conductedByName","notes","publicVisible","externallyReportedAt","externalReportRef","stateReportCategory","createdAt","updatedAt","deletedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/safety-drills/report-filed":{"post":{"summary":"Mark all unreported drills for (school, schoolYear) as filed","tags":["Safety"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"externalReportRef":{"type":"string","maxLength":100}},"required":["schoolId","schoolYearId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"rows":{"type":"array","items":{"type":"object","properties":{"schoolId":{"type":"string","format":"uuid"},"schoolName":{"type":"string"},"totals":{"type":"object","properties":{"fire":{"type":"integer","minimum":0},"non_fire_security":{"type":"integer","minimum":0},"bus_evacuation":{"type":"integer","minimum":0},"other":{"type":"integer","minimum":0},"announced":{"type":"integer","minimum":0},"unannounced":{"type":"integer","minimum":0},"pendingReport":{"type":"integer","minimum":0}},"required":["fire","non_fire_security","bus_evacuation","other","announced","unannounced","pendingReport"],"additionalProperties":false}},"required":["schoolId","schoolName","totals"],"additionalProperties":false}}},"required":["schoolYearId","rows"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/schools/{schoolId}/safety/public-drills":{"get":{"summary":"Parent-facing drill list (date, type, duration only)","tags":["Safety"],"description":"No authentication required. Caller supplies districtId via the X-District-Id header (same mechanism the other dev-header routes use). Only drills flagged publicVisible=true are returned.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"schoolId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"schoolId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"drills":{"type":"array","items":{"type":"object","properties":{"drillDate":{"type":"string","format":"date"},"drillType":{"type":"string","enum":["fire","lockdown","shelter_in_place","evacuation","bus_evacuation","severe_weather","bomb_threat","other"]},"durationSeconds":{"type":"integer","nullable":true}},"required":["drillDate","drillType","durationSeconds"],"additionalProperties":false}}},"required":["schoolId","schoolYearId","drills"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/district-calendar":{"get":{"summary":"List all calendar days for a school year (school overrides folded in if schoolId is passed)","tags":["District Calendar"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"totalInstructionalDays":{"type":"integer","minimum":0},"totalInstructionalMinutes":{"type":"integer","minimum":0},"days":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"dayType":{"type":"string","enum":["instructional","half_day","early_dismissal","delayed_opening","holiday","professional_development","teacher_inservice","weekend","emergency_closure","snow_day","other"]},"countsAsInstructional":{"type":"boolean"},"instructionalMinutes":{"type":"integer","nullable":true},"reason":{"type":"string","nullable":true},"overrideDayType":{"type":"string","enum":["instructional","half_day","early_dismissal","delayed_opening","holiday","professional_development","teacher_inservice","weekend","emergency_closure","snow_day","other"],"nullable":true},"overrideReason":{"type":"string","nullable":true},"effectiveDayType":{"type":"string","enum":["instructional","half_day","early_dismissal","delayed_opening","holiday","professional_development","teacher_inservice","weekend","emergency_closure","snow_day","other"]},"effectiveCountsAsInstructional":{"type":"boolean"},"effectiveInstructionalMinutes":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","schoolYearId","date","dayType","countsAsInstructional","instructionalMinutes","reason","effectiveDayType","effectiveCountsAsInstructional","effectiveInstructionalMinutes","createdAt","updatedAt","deletedAt"],"additionalProperties":false}}},"required":["schoolYearId","schoolId","totalInstructionalDays","totalInstructionalMinutes","days"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/district-calendar/publish":{"post":{"summary":"Bulk-publish or re-publish the district calendar for a school year (emits CalendarPublished)","tags":["District Calendar"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"dayType":{"type":"string","enum":["instructional","half_day","early_dismissal","delayed_opening","holiday","professional_development","teacher_inservice","weekend","emergency_closure","snow_day","other"]},"countsAsInstructional":{"type":"boolean"},"instructionalMinutes":{"type":"integer","minimum":0,"maximum":900,"nullable":true},"reason":{"type":"string","maxLength":200,"nullable":true}},"required":["date","dayType"],"additionalProperties":false},"minItems":1,"maxItems":500}},"required":["schoolYearId","days"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"dayCount":{"type":"integer","minimum":0}},"required":["schoolYearId","dayCount"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/district-calendar/days/{date}":{"patch":{"summary":"Create or edit a single district calendar day (emits CalendarDaySet)","tags":["District Calendar"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"dayType":{"type":"string","enum":["instructional","half_day","early_dismissal","delayed_opening","holiday","professional_development","teacher_inservice","weekend","emergency_closure","snow_day","other"]},"countsAsInstructional":{"type":"boolean"},"instructionalMinutes":{"type":"integer","minimum":0,"maximum":900,"nullable":true},"reason":{"type":"string","maxLength":200,"nullable":true}},"required":["schoolYearId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"in":"path","name":"date","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolYearId":{"type":"string","format":"uuid"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"dayType":{"type":"string","enum":["instructional","half_day","early_dismissal","delayed_opening","holiday","professional_development","teacher_inservice","weekend","emergency_closure","snow_day","other"]},"countsAsInstructional":{"type":"boolean"},"instructionalMinutes":{"type":"integer","nullable":true},"reason":{"type":"string","nullable":true},"overrideDayType":{"type":"string","enum":["instructional","half_day","early_dismissal","delayed_opening","holiday","professional_development","teacher_inservice","weekend","emergency_closure","snow_day","other"],"nullable":true},"overrideReason":{"type":"string","nullable":true},"effectiveDayType":{"type":"string","enum":["instructional","half_day","early_dismissal","delayed_opening","holiday","professional_development","teacher_inservice","weekend","emergency_closure","snow_day","other"]},"effectiveCountsAsInstructional":{"type":"boolean"},"effectiveInstructionalMinutes":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","schoolYearId","date","dayType","countsAsInstructional","instructionalMinutes","reason","effectiveDayType","effectiveCountsAsInstructional","effectiveInstructionalMinutes","createdAt","updatedAt","deletedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Soft-delete a district calendar day (emits CalendarDayCleared)","tags":["District Calendar"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":true},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"in":"path","name":"date","required":true}],"responses":{"204":{"description":"Default Response","content":{"application/json":{"schema":{"enum":["null"],"nullable":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/schools/{schoolId}/calendar-overrides":{"post":{"summary":"Create or replace a school-level calendar override (emits SchoolCalendarDayOverridden)","tags":["District Calendar"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"dayType":{"type":"string","enum":["instructional","half_day","early_dismissal","delayed_opening","holiday","professional_development","teacher_inservice","weekend","emergency_closure","snow_day","other"]},"countsAsInstructional":{"type":"boolean"},"instructionalMinutes":{"type":"integer","minimum":0,"maximum":900,"nullable":true},"reason":{"type":"string","maxLength":200,"nullable":true}},"required":["date","dayType"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"schoolId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"districtCalendarDayId":{"type":"string","format":"uuid"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"dayType":{"type":"string","enum":["instructional","half_day","early_dismissal","delayed_opening","holiday","professional_development","teacher_inservice","weekend","emergency_closure","snow_day","other"]},"countsAsInstructional":{"type":"boolean"},"instructionalMinutes":{"type":"integer","nullable":true},"reason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","districtCalendarDayId","date","dayType","countsAsInstructional","instructionalMinutes","reason","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/schools/{schoolId}/calendar-overrides/{date}":{"delete":{"summary":"Clear a school-level calendar override (emits SchoolCalendarOverrideCleared)","tags":["District Calendar"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"schoolId","required":true},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"in":"path","name":"date","required":true}],"responses":{"204":{"description":"Default Response","content":{"application/json":{"schema":{"enum":["null"],"nullable":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/district-calendar/school-months":{"get":{"summary":"Enumerate NJDOE school months (20 consecutive instructional days)","tags":["District Calendar"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"months":{"type":"array","items":{"type":"object","properties":{"monthIndex":{"type":"integer","exclusiveMinimum":true,"minimum":0},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"instructionalDayCount":{"type":"integer","minimum":0}},"required":["monthIndex","startDate","endDate","instructionalDayCount"],"additionalProperties":false}}},"required":["schoolYearId","schoolId","months"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/district-calendar/nth-school-day":{"get":{"summary":"Compute the Nth instructional day from a starting date (HIB 10-school-day clock, truancy)","tags":["District Calendar"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolYearId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"in":"query","name":"from","required":true},{"schema":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":400},"in":"query","name":"n","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"schoolYearId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"n":{"type":"integer","exclusiveMinimum":true,"minimum":0},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"ranOut":{"type":"boolean"}},"required":["schoolYearId","schoolId","from","n","date","ranOut"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/feature-flags":{"get":{"summary":"Effective feature flags for the current district","tags":["Feature Flags"],"description":"Returns all platform feature flags resolved for this district. District-level overrides take precedence over platform defaults. Expired overrides are ignored.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"source":{"type":"string","enum":["override","default"]}},"required":["key","description","enabled","source"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/extracurriculars":{"get":{"summary":"List extracurricular activities","tags":["Extracurriculars"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","enum":["sport","club","performing_arts","academic_team","other"]},"in":"query","name":"activityType","required":false},{"schema":{"type":"string","enum":["fall","winter","spring","year_round"]},"in":"query","name":"season","required":false},{"schema":{"type":"string"},"in":"query","name":"isActive","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string"},"name":{"type":"string"},"activityType":{"type":"string"},"season":{"type":"string","nullable":true},"minGpa":{"type":"string","nullable":true},"requiresPhysical":{"type":"boolean"},"requiresConsent":{"type":"boolean"},"maxRosterSize":{"type":"integer","nullable":true},"coachPersonId":{"type":"string","nullable":true},"coachName":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","name","activityType","season","minGpa","requiresPhysical","requiresConsent","maxRosterSize","coachPersonId","coachName","isActive","notes","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create an extracurricular activity","tags":["Extracurriculars"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schoolId":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":200},"activityType":{"type":"string","enum":["sport","club","performing_arts","academic_team","other"]},"season":{"type":"string","enum":["fall","winter","spring","year_round"]},"minGpa":{"type":"number","minimum":0,"maximum":4},"requiresPhysical":{"type":"boolean","default":false},"requiresConsent":{"type":"boolean","default":true},"maxRosterSize":{"type":"integer","minimum":1},"coachPersonId":{"type":"string","format":"uuid"},"coachName":{"type":"string","maxLength":200},"isActive":{"type":"boolean","default":true},"notes":{"type":"string","maxLength":5000}},"required":["schoolId","name","activityType"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string"},"name":{"type":"string"},"activityType":{"type":"string"},"season":{"type":"string","nullable":true},"minGpa":{"type":"string","nullable":true},"requiresPhysical":{"type":"boolean"},"requiresConsent":{"type":"boolean"},"maxRosterSize":{"type":"integer","nullable":true},"coachPersonId":{"type":"string","nullable":true},"coachName":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","name","activityType","season","minGpa","requiresPhysical","requiresConsent","maxRosterSize","coachPersonId","coachName","isActive","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/extracurriculars/{id}":{"get":{"summary":"Get a single extracurricular activity","tags":["Extracurriculars"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string"},"name":{"type":"string"},"activityType":{"type":"string"},"season":{"type":"string","nullable":true},"minGpa":{"type":"string","nullable":true},"requiresPhysical":{"type":"boolean"},"requiresConsent":{"type":"boolean"},"maxRosterSize":{"type":"integer","nullable":true},"coachPersonId":{"type":"string","nullable":true},"coachName":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","name","activityType","season","minGpa","requiresPhysical","requiresConsent","maxRosterSize","coachPersonId","coachName","isActive","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update an extracurricular activity","tags":["Extracurriculars"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"activityType":{"type":"string","enum":["sport","club","performing_arts","academic_team","other"]},"season":{"type":"string","enum":["fall","winter","spring","year_round"]},"minGpa":{"type":"number","minimum":0,"maximum":4,"nullable":true},"requiresPhysical":{"type":"boolean"},"requiresConsent":{"type":"boolean"},"maxRosterSize":{"type":"integer","minimum":1,"nullable":true},"coachPersonId":{"type":"string","format":"uuid","nullable":true},"coachName":{"type":"string","maxLength":200,"nullable":true},"isActive":{"type":"boolean"},"notes":{"type":"string","maxLength":5000,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string"},"name":{"type":"string"},"activityType":{"type":"string"},"season":{"type":"string","nullable":true},"minGpa":{"type":"string","nullable":true},"requiresPhysical":{"type":"boolean"},"requiresConsent":{"type":"boolean"},"maxRosterSize":{"type":"integer","nullable":true},"coachPersonId":{"type":"string","nullable":true},"coachName":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","name","activityType","season","minGpa","requiresPhysical","requiresConsent","maxRosterSize","coachPersonId","coachName","isActive","notes","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/extracurriculars/{id}/roster":{"get":{"summary":"Get the roster for an extracurricular activity","tags":["Extracurriculars"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"extracurricularId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"status":{"type":"string"},"eligibilityCheckedAt":{"type":"string","format":"date-time","nullable":true},"eligibilityNotes":{"type":"string","nullable":true},"consentGivenAt":{"type":"string","format":"date-time","nullable":true},"consentGivenByPersonId":{"type":"string","nullable":true},"enrolledAt":{"type":"string","format":"date-time","nullable":true},"droppedAt":{"type":"string","format":"date-time","nullable":true},"dropReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","extracurricularId","studentPersonId","status","eligibilityCheckedAt","eligibilityNotes","consentGivenAt","consentGivenByPersonId","enrolledAt","droppedAt","dropReason","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Add a student to the roster (runs eligibility check)","tags":["Extracurriculars"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"}},"required":["studentId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"extracurricularId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"status":{"type":"string"},"eligibilityCheckedAt":{"type":"string","format":"date-time","nullable":true},"eligibilityNotes":{"type":"string","nullable":true},"consentGivenAt":{"type":"string","format":"date-time","nullable":true},"consentGivenByPersonId":{"type":"string","nullable":true},"enrolledAt":{"type":"string","format":"date-time","nullable":true},"droppedAt":{"type":"string","format":"date-time","nullable":true},"dropReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","extracurricularId","studentPersonId","status","eligibilityCheckedAt","eligibilityNotes","consentGivenAt","consentGivenByPersonId","enrolledAt","droppedAt","dropReason","createdAt","updatedAt"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["entry","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/extracurriculars/{id}/roster/{studentId}":{"delete":{"summary":"Drop a student from the roster","tags":["Extracurriculars"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":200}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"studentId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"}},"required":["eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/extracurriculars/{id}/eligibility/{studentId}":{"get":{"summary":"Check eligibility for a single student","tags":["Extracurriculars"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"studentId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"eligible":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}},"gpaOk":{"type":"boolean"},"physicalOk":{"type":"boolean"},"consentOk":{"type":"boolean"}},"required":["studentId","eligible","reasons","gpaOk","physicalOk","consentOk"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/extracurriculars/{id}/consent/{studentId}":{"post":{"summary":"Record parental consent for a student","tags":["Extracurriculars"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"givenByPersonId":{"type":"string","format":"uuid"}},"required":["givenByPersonId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"studentId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"}},"required":["eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/extracurriculars/{id}/eligibility-report":{"get":{"summary":"Run eligibility check for all rostered students and return report","tags":["Extracurriculars"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"entry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"extracurricularId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"status":{"type":"string"},"eligibilityCheckedAt":{"type":"string","format":"date-time","nullable":true},"eligibilityNotes":{"type":"string","nullable":true},"consentGivenAt":{"type":"string","format":"date-time","nullable":true},"consentGivenByPersonId":{"type":"string","nullable":true},"enrolledAt":{"type":"string","format":"date-time","nullable":true},"droppedAt":{"type":"string","format":"date-time","nullable":true},"dropReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","extracurricularId","studentPersonId","status","eligibilityCheckedAt","eligibilityNotes","consentGivenAt","consentGivenByPersonId","enrolledAt","droppedAt","dropReason","createdAt","updatedAt"],"additionalProperties":false},"eligibility":{"type":"object","properties":{"studentId":{"type":"string","format":"uuid"},"eligible":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}},"gpaOk":{"type":"boolean"},"physicalOk":{"type":"boolean"},"consentOk":{"type":"boolean"}},"required":["studentId","eligible","reasons","gpaOk","physicalOk","consentOk"],"additionalProperties":false}},"required":["entry","eligibility"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/health/physical-exams":{"post":{"summary":"Record a pre-participation physical examination","tags":["Health","Extracurriculars"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"studentPersonId":{"type":"string","format":"uuid"},"examDate":{"type":"string","format":"date"},"expiresAt":{"type":"string","format":"date"},"clearanceStatus":{"type":"string","enum":["cleared","cleared_with_restrictions","not_cleared"]},"restrictions":{"type":"string","maxLength":5000},"physicianName":{"type":"string","maxLength":200},"extracurricularId":{"type":"string","format":"uuid"}},"required":["studentPersonId","examDate","expiresAt","clearanceStatus"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"exam":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"examDate":{"type":"string","format":"date"},"expiresAt":{"type":"string","format":"date"},"clearanceStatus":{"type":"string"},"restrictions":{"type":"string","nullable":true},"physicianName":{"type":"string","nullable":true},"extracurricularId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","studentPersonId","examDate","expiresAt","clearanceStatus","restrictions","physicianName","extracurricularId","createdAt","updatedAt"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["exam","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"get":{"summary":"List physical examinations (filter by studentId)","tags":["Health","Extracurriculars"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"string","enum":["cleared","cleared_with_restrictions","not_cleared"]},"in":"query","name":"clearanceStatus","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"examDate":{"type":"string","format":"date"},"expiresAt":{"type":"string","format":"date"},"clearanceStatus":{"type":"string"},"restrictions":{"type":"string","nullable":true},"physicianName":{"type":"string","nullable":true},"extracurricularId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","studentPersonId","examDate","expiresAt","clearanceStatus","restrictions","physicianName","extracurricularId","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assessments/results":{"get":{"summary":"List assessment results across the district","tags":["Assessments"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"studentId","required":false},{"schema":{"type":"string","enum":["njsla","sbac","staar"]},"in":"query","name":"assessmentType","required":false},{"schema":{"type":"integer","minimum":2000,"maximum":2100},"in":"query","name":"testYear","required":false},{"schema":{"type":"string","maxLength":50},"in":"query","name":"subject","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"assessmentType":{"type":"string"},"testYear":{"type":"integer"},"subject":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"scaleScore":{"type":"integer","nullable":true},"performanceLevel":{"type":"integer","nullable":true},"performanceLabel":{"type":"string","nullable":true},"percentileRank":{"type":"integer","nullable":true},"rawScore":{"type":"integer","nullable":true},"metadata":{"type":"object","additionalProperties":{}},"importId":{"type":"string","nullable":true},"importedByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","studentPersonId","assessmentType","testYear","subject","gradeLevel","scaleScore","performanceLevel","performanceLabel","percentileRank","rawScore","metadata","importId","importedByUserId","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/students/{studentId}/assessment-results":{"get":{"summary":"Get all assessment results for a student","tags":["Assessments"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"studentId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"assessmentType":{"type":"string"},"testYear":{"type":"integer"},"subject":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"scaleScore":{"type":"integer","nullable":true},"performanceLevel":{"type":"integer","nullable":true},"performanceLabel":{"type":"string","nullable":true},"percentileRank":{"type":"integer","nullable":true},"rawScore":{"type":"integer","nullable":true},"metadata":{"type":"object","additionalProperties":{}},"importId":{"type":"string","nullable":true},"importedByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","studentPersonId","assessmentType","testYear","subject","gradeLevel","scaleScore","performanceLevel","performanceLabel","percentileRank","rawScore","metadata","importId","importedByUserId","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assessments/import/preview":{"post":{"summary":"Preview a CSV import — parse and match students without persisting","tags":["Assessments"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"adapter":{"type":"string","enum":["njsla","sbac","staar"]},"filename":{"type":"string","minLength":1,"maxLength":500},"csvText":{"type":"string","minLength":1,"maxLength":52428800}},"required":["adapter","filename","csvText"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"adapter":{"type":"string","enum":["njsla","sbac","staar"]},"filename":{"type":"string"},"totalRows":{"type":"integer"},"validRows":{"type":"integer"},"invalidRows":{"type":"integer"},"unmatchedRows":{"type":"integer"},"rows":{"type":"array","items":{"type":"object","properties":{"rowIndex":{"type":"integer"},"localStudentId":{"type":"string"},"assessmentType":{"type":"string"},"testYear":{"type":"integer"},"subject":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"scaleScore":{"type":"integer","nullable":true},"performanceLevel":{"type":"integer","nullable":true},"performanceLabel":{"type":"string","nullable":true},"percentileRank":{"type":"integer","nullable":true},"rawScore":{"type":"integer","nullable":true},"metadata":{"type":"object","additionalProperties":{}},"matchedStudentPersonId":{"type":"string","format":"uuid","nullable":true},"matchWarning":{"type":"string","nullable":true}},"required":["rowIndex","localStudentId","assessmentType","testYear","subject","gradeLevel","scaleScore","performanceLevel","performanceLabel","percentileRank","rawScore","metadata","matchedStudentPersonId","matchWarning"],"additionalProperties":false}},"errors":{"type":"array","items":{"type":"object","properties":{"rowIndex":{"type":"integer"},"message":{"type":"string"}},"required":["rowIndex","message"],"additionalProperties":false}}},"required":["adapter","filename","totalRows","validRows","invalidRows","unmatchedRows","rows","errors"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assessments/import/apply":{"post":{"summary":"Apply a previewed import — persist assessment results","tags":["Assessments"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"adapter":{"type":"string","enum":["njsla","sbac","staar"]},"filename":{"type":"string","minLength":1,"maxLength":500},"rows":{"type":"array","items":{"type":"object","properties":{"localStudentId":{"type":"string"},"assessmentType":{"type":"string"},"testYear":{"type":"integer"},"subject":{"type":"string"},"gradeLevel":{"type":"string","nullable":true},"scaleScore":{"type":"integer","nullable":true},"performanceLevel":{"type":"integer","nullable":true},"performanceLabel":{"type":"string","nullable":true},"percentileRank":{"type":"integer","nullable":true},"rawScore":{"type":"integer","nullable":true},"metadata":{"type":"object","additionalProperties":{}},"matchedStudentPersonId":{"type":"string","format":"uuid","nullable":true}},"required":["localStudentId","assessmentType","testYear","subject","gradeLevel","scaleScore","performanceLevel","performanceLabel","percentileRank","rawScore","metadata","matchedStudentPersonId"],"additionalProperties":false},"minItems":1,"maxItems":50000}},"required":["adapter","filename","rows"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"importId":{"type":"string","format":"uuid"},"status":{"type":"string"},"totalRows":{"type":"integer"},"successRows":{"type":"integer"},"errorRows":{"type":"integer"},"eventId":{"type":"string","format":"uuid"}},"required":["importId","status","totalRows","successRows","errorRows","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assessments/imports":{"get":{"summary":"List assessment import history","tags":["Assessments"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"adapter":{"type":"string"},"filename":{"type":"string"},"status":{"type":"string"},"totalRows":{"type":"integer"},"processedRows":{"type":"integer"},"successRows":{"type":"integer"},"errorRows":{"type":"integer"},"errorLog":{"type":"array","items":{"type":"object","additionalProperties":{}}},"importedByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","adapter","filename","status","totalRows","processedRows","successRows","errorRows","errorLog","importedByUserId","createdAt","completedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/assessments/imports/{id}":{"get":{"summary":"Get an assessment import record","tags":["Assessments"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"adapter":{"type":"string"},"filename":{"type":"string"},"status":{"type":"string"},"totalRows":{"type":"integer"},"processedRows":{"type":"integer"},"successRows":{"type":"integer"},"errorRows":{"type":"integer"},"errorLog":{"type":"array","items":{"type":"object","additionalProperties":{}}},"importedByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","adapter","filename","status","totalRows","processedRows","successRows","errorRows","errorLog","importedByUserId","createdAt","completedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/students/{studentId}/transfers":{"get":{"summary":"List transfer requests for a student","tags":["Transfers"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"studentId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"direction":{"type":"string"},"status":{"type":"string"},"receivingDistrictName":{"type":"string","nullable":true},"receivingDistrictId":{"type":"string","nullable":true},"sendingDistrictName":{"type":"string","nullable":true},"adapter":{"type":"string"},"packagedRecordsUrl":{"type":"string","nullable":true},"packagedAt":{"type":"string","format":"date-time","nullable":true},"receivedAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"transferDate":{"type":"string","format":"date"},"notes":{"type":"string","nullable":true},"requestedByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","studentPersonId","direction","status","receivingDistrictName","receivingDistrictId","sendingDistrictName","adapter","packagedRecordsUrl","packagedAt","receivedAt","completedAt","transferDate","notes","requestedByUserId","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Initiate an outbound transfer for a student","tags":["Transfers"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"receivingDistrictName":{"type":"string","maxLength":200},"receivingDistrictId":{"type":"string","format":"uuid"},"adapter":{"type":"string","enum":["trex","roeontnet","manual","other"],"default":"manual"},"transferDate":{"type":"string","format":"date"},"notes":{"type":"string","maxLength":5000}},"required":["transferDate"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"studentId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"direction":{"type":"string"},"status":{"type":"string"},"receivingDistrictName":{"type":"string","nullable":true},"receivingDistrictId":{"type":"string","nullable":true},"sendingDistrictName":{"type":"string","nullable":true},"adapter":{"type":"string"},"packagedRecordsUrl":{"type":"string","nullable":true},"packagedAt":{"type":"string","format":"date-time","nullable":true},"receivedAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"transferDate":{"type":"string","format":"date"},"notes":{"type":"string","nullable":true},"requestedByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","studentPersonId","direction","status","receivingDistrictName","receivingDistrictId","sendingDistrictName","adapter","packagedRecordsUrl","packagedAt","receivedAt","completedAt","transferDate","notes","requestedByUserId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transfers/{id}":{"get":{"summary":"Get a single transfer request","tags":["Transfers"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"direction":{"type":"string"},"status":{"type":"string"},"receivingDistrictName":{"type":"string","nullable":true},"receivingDistrictId":{"type":"string","nullable":true},"sendingDistrictName":{"type":"string","nullable":true},"adapter":{"type":"string"},"packagedRecordsUrl":{"type":"string","nullable":true},"packagedAt":{"type":"string","format":"date-time","nullable":true},"receivedAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"transferDate":{"type":"string","format":"date"},"notes":{"type":"string","nullable":true},"requestedByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","studentPersonId","direction","status","receivingDistrictName","receivingDistrictId","sendingDistrictName","adapter","packagedRecordsUrl","packagedAt","receivedAt","completedAt","transferDate","notes","requestedByUserId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update status or notes on a transfer request","tags":["Transfers"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["initiated","pending_records","records_sent","completed","cancelled"]},"notes":{"type":"string","maxLength":5000},"receivingDistrictName":{"type":"string","maxLength":200}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"direction":{"type":"string"},"status":{"type":"string"},"receivingDistrictName":{"type":"string","nullable":true},"receivingDistrictId":{"type":"string","nullable":true},"sendingDistrictName":{"type":"string","nullable":true},"adapter":{"type":"string"},"packagedRecordsUrl":{"type":"string","nullable":true},"packagedAt":{"type":"string","format":"date-time","nullable":true},"receivedAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"transferDate":{"type":"string","format":"date"},"notes":{"type":"string","nullable":true},"requestedByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","studentPersonId","direction","status","receivingDistrictName","receivingDistrictId","sendingDistrictName","adapter","packagedRecordsUrl","packagedAt","receivedAt","completedAt","transferDate","notes","requestedByUserId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transfers/{id}/package-records":{"post":{"summary":"Package student records using the configured adapter","tags":["Transfers"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"transferId":{"type":"string","format":"uuid"},"packagedRecordsUrl":{"type":"string"},"packagedAt":{"type":"string","format":"date-time"},"eventId":{"type":"string","format":"uuid"}},"required":["transferId","packagedRecordsUrl","packagedAt","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/transfers/{id}/complete":{"post":{"summary":"Mark a transfer as completed","tags":["Transfers"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","maxLength":5000}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"}},"required":["eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/purchase-orders":{"get":{"summary":"List purchase orders","tags":["Purchase Orders"],"parameters":[{"schema":{"type":"string","enum":["draft","submitted","approved","partially_received","fulfilled","cancelled"]},"in":"query","name":"status","required":false},{"schema":{"type":"integer"},"in":"query","name":"fiscalYear","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string"},"in":"query","name":"vendorName","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","nullable":true},"poNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"vendorName":{"type":"string"},"vendorId":{"type":"string","nullable":true},"status":{"type":"string"},"totalCents":{"type":"integer"},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"fulfilledAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"budgetCode":{"type":"string","nullable":true},"fiscalYear":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true},"createdByUserId":{"type":"string","nullable":true},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"description":{"type":"string"},"quantity":{"type":"integer"},"unitCostCents":{"type":"integer"},"totalCents":{"type":"integer"},"receivedQuantity":{"type":"integer"},"category":{"type":"string","nullable":true},"accountCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","sortOrder","description","quantity","unitCostCents","totalCents","receivedQuantity","category","accountCode","createdAt","updatedAt"],"additionalProperties":false}},"approvals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"approverUserId":{"type":"string","format":"uuid"},"decision":{"type":"string"},"decisionAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","approverUserId","decision","decisionAt","notes","createdAt","updatedAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","poNumber","title","description","vendorName","vendorId","status","totalCents","approvedByUserId","approvedAt","fulfilledAt","cancelledAt","cancelledReason","budgetCode","fiscalYear","notes","createdByUserId","lineItems","approvals","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a purchase order draft","tags":["Purchase Orders"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":5000},"vendorName":{"type":"string","minLength":1,"maxLength":200},"vendorId":{"type":"string","maxLength":100},"schoolId":{"type":"string","format":"uuid"},"budgetCode":{"type":"string","maxLength":80},"fiscalYear":{"type":"integer","minimum":2020,"maximum":2099},"notes":{"type":"string","maxLength":10000}},"required":["title","vendorName"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","nullable":true},"poNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"vendorName":{"type":"string"},"vendorId":{"type":"string","nullable":true},"status":{"type":"string"},"totalCents":{"type":"integer"},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"fulfilledAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"budgetCode":{"type":"string","nullable":true},"fiscalYear":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true},"createdByUserId":{"type":"string","nullable":true},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"description":{"type":"string"},"quantity":{"type":"integer"},"unitCostCents":{"type":"integer"},"totalCents":{"type":"integer"},"receivedQuantity":{"type":"integer"},"category":{"type":"string","nullable":true},"accountCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","sortOrder","description","quantity","unitCostCents","totalCents","receivedQuantity","category","accountCode","createdAt","updatedAt"],"additionalProperties":false}},"approvals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"approverUserId":{"type":"string","format":"uuid"},"decision":{"type":"string"},"decisionAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","approverUserId","decision","decisionAt","notes","createdAt","updatedAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","poNumber","title","description","vendorName","vendorId","status","totalCents","approvedByUserId","approvedAt","fulfilledAt","cancelledAt","cancelledReason","budgetCode","fiscalYear","notes","createdByUserId","lineItems","approvals","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/purchase-orders/{id}":{"get":{"summary":"Get a single purchase order with line items and approvals","tags":["Purchase Orders"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","nullable":true},"poNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"vendorName":{"type":"string"},"vendorId":{"type":"string","nullable":true},"status":{"type":"string"},"totalCents":{"type":"integer"},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"fulfilledAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"budgetCode":{"type":"string","nullable":true},"fiscalYear":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true},"createdByUserId":{"type":"string","nullable":true},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"description":{"type":"string"},"quantity":{"type":"integer"},"unitCostCents":{"type":"integer"},"totalCents":{"type":"integer"},"receivedQuantity":{"type":"integer"},"category":{"type":"string","nullable":true},"accountCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","sortOrder","description","quantity","unitCostCents","totalCents","receivedQuantity","category","accountCode","createdAt","updatedAt"],"additionalProperties":false}},"approvals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"approverUserId":{"type":"string","format":"uuid"},"decision":{"type":"string"},"decisionAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","approverUserId","decision","decisionAt","notes","createdAt","updatedAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","poNumber","title","description","vendorName","vendorId","status","totalCents","approvedByUserId","approvedAt","fulfilledAt","cancelledAt","cancelledReason","budgetCode","fiscalYear","notes","createdByUserId","lineItems","approvals","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update PO metadata (only before approval)","tags":["Purchase Orders"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":5000},"vendorName":{"type":"string","minLength":1,"maxLength":200},"vendorId":{"type":"string","maxLength":100},"schoolId":{"type":"string","format":"uuid","nullable":true},"budgetCode":{"type":"string","maxLength":80},"fiscalYear":{"type":"integer","minimum":2020,"maximum":2099},"notes":{"type":"string","maxLength":10000}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","nullable":true},"poNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"vendorName":{"type":"string"},"vendorId":{"type":"string","nullable":true},"status":{"type":"string"},"totalCents":{"type":"integer"},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"fulfilledAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"budgetCode":{"type":"string","nullable":true},"fiscalYear":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true},"createdByUserId":{"type":"string","nullable":true},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"description":{"type":"string"},"quantity":{"type":"integer"},"unitCostCents":{"type":"integer"},"totalCents":{"type":"integer"},"receivedQuantity":{"type":"integer"},"category":{"type":"string","nullable":true},"accountCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","sortOrder","description","quantity","unitCostCents","totalCents","receivedQuantity","category","accountCode","createdAt","updatedAt"],"additionalProperties":false}},"approvals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"approverUserId":{"type":"string","format":"uuid"},"decision":{"type":"string"},"decisionAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","approverUserId","decision","decisionAt","notes","createdAt","updatedAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","poNumber","title","description","vendorName","vendorId","status","totalCents","approvedByUserId","approvedAt","fulfilledAt","cancelledAt","cancelledReason","budgetCode","fiscalYear","notes","createdByUserId","lineItems","approvals","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/purchase-orders/{id}/line-items":{"post":{"summary":"Add a line item to a PO","tags":["Purchase Orders"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":500},"quantity":{"type":"integer","minimum":1},"unitCostCents":{"type":"integer","minimum":0},"category":{"type":"string","maxLength":100},"accountCode":{"type":"string","maxLength":80},"sortOrder":{"type":"integer","minimum":0,"default":0}},"required":["description","quantity","unitCostCents"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"description":{"type":"string"},"quantity":{"type":"integer"},"unitCostCents":{"type":"integer"},"totalCents":{"type":"integer"},"receivedQuantity":{"type":"integer"},"category":{"type":"string","nullable":true},"accountCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","sortOrder","description","quantity","unitCostCents","totalCents","receivedQuantity","category","accountCode","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/purchase-orders/{id}/line-items/{itemId}":{"patch":{"summary":"Update a PO line item","tags":["Purchase Orders"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":500},"quantity":{"type":"integer","minimum":1},"unitCostCents":{"type":"integer","minimum":0},"category":{"type":"string","maxLength":100,"nullable":true},"accountCode":{"type":"string","maxLength":80,"nullable":true},"sortOrder":{"type":"integer","minimum":0}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"itemId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"description":{"type":"string"},"quantity":{"type":"integer"},"unitCostCents":{"type":"integer"},"totalCents":{"type":"integer"},"receivedQuantity":{"type":"integer"},"category":{"type":"string","nullable":true},"accountCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","sortOrder","description","quantity","unitCostCents","totalCents","receivedQuantity","category","accountCode","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Remove a line item from a PO","tags":["Purchase Orders"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"itemId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/purchase-orders/{id}/submit":{"post":{"summary":"Submit a draft PO for approval","tags":["Purchase Orders"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","nullable":true},"poNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"vendorName":{"type":"string"},"vendorId":{"type":"string","nullable":true},"status":{"type":"string"},"totalCents":{"type":"integer"},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"fulfilledAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"budgetCode":{"type":"string","nullable":true},"fiscalYear":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true},"createdByUserId":{"type":"string","nullable":true},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"description":{"type":"string"},"quantity":{"type":"integer"},"unitCostCents":{"type":"integer"},"totalCents":{"type":"integer"},"receivedQuantity":{"type":"integer"},"category":{"type":"string","nullable":true},"accountCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","sortOrder","description","quantity","unitCostCents","totalCents","receivedQuantity","category","accountCode","createdAt","updatedAt"],"additionalProperties":false}},"approvals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"approverUserId":{"type":"string","format":"uuid"},"decision":{"type":"string"},"decisionAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","approverUserId","decision","decisionAt","notes","createdAt","updatedAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","poNumber","title","description","vendorName","vendorId","status","totalCents","approvedByUserId","approvedAt","fulfilledAt","cancelledAt","cancelledReason","budgetCode","fiscalYear","notes","createdByUserId","lineItems","approvals","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/purchase-orders/{id}/approve":{"post":{"summary":"Approve a submitted PO","tags":["Purchase Orders"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","maxLength":1000}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","nullable":true},"poNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"vendorName":{"type":"string"},"vendorId":{"type":"string","nullable":true},"status":{"type":"string"},"totalCents":{"type":"integer"},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"fulfilledAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"budgetCode":{"type":"string","nullable":true},"fiscalYear":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true},"createdByUserId":{"type":"string","nullable":true},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"description":{"type":"string"},"quantity":{"type":"integer"},"unitCostCents":{"type":"integer"},"totalCents":{"type":"integer"},"receivedQuantity":{"type":"integer"},"category":{"type":"string","nullable":true},"accountCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","sortOrder","description","quantity","unitCostCents","totalCents","receivedQuantity","category","accountCode","createdAt","updatedAt"],"additionalProperties":false}},"approvals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"approverUserId":{"type":"string","format":"uuid"},"decision":{"type":"string"},"decisionAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","approverUserId","decision","decisionAt","notes","createdAt","updatedAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","poNumber","title","description","vendorName","vendorId","status","totalCents","approvedByUserId","approvedAt","fulfilledAt","cancelledAt","cancelledReason","budgetCode","fiscalYear","notes","createdByUserId","lineItems","approvals","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/purchase-orders/{id}/reject":{"post":{"summary":"Reject a submitted PO","tags":["Purchase Orders"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","nullable":true},"poNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"vendorName":{"type":"string"},"vendorId":{"type":"string","nullable":true},"status":{"type":"string"},"totalCents":{"type":"integer"},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"fulfilledAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"budgetCode":{"type":"string","nullable":true},"fiscalYear":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true},"createdByUserId":{"type":"string","nullable":true},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"description":{"type":"string"},"quantity":{"type":"integer"},"unitCostCents":{"type":"integer"},"totalCents":{"type":"integer"},"receivedQuantity":{"type":"integer"},"category":{"type":"string","nullable":true},"accountCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","sortOrder","description","quantity","unitCostCents","totalCents","receivedQuantity","category","accountCode","createdAt","updatedAt"],"additionalProperties":false}},"approvals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"approverUserId":{"type":"string","format":"uuid"},"decision":{"type":"string"},"decisionAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","approverUserId","decision","decisionAt","notes","createdAt","updatedAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","poNumber","title","description","vendorName","vendorId","status","totalCents","approvedByUserId","approvedAt","fulfilledAt","cancelledAt","cancelledReason","budgetCode","fiscalYear","notes","createdByUserId","lineItems","approvals","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/purchase-orders/{id}/receive-items":{"post":{"summary":"Record received quantity for a line item","tags":["Purchase Orders"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"lineItemId":{"type":"string","format":"uuid"},"receivedQuantity":{"type":"integer","minimum":0}},"required":["lineItemId","receivedQuantity"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","nullable":true},"poNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"vendorName":{"type":"string"},"vendorId":{"type":"string","nullable":true},"status":{"type":"string"},"totalCents":{"type":"integer"},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"fulfilledAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"budgetCode":{"type":"string","nullable":true},"fiscalYear":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true},"createdByUserId":{"type":"string","nullable":true},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"description":{"type":"string"},"quantity":{"type":"integer"},"unitCostCents":{"type":"integer"},"totalCents":{"type":"integer"},"receivedQuantity":{"type":"integer"},"category":{"type":"string","nullable":true},"accountCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","sortOrder","description","quantity","unitCostCents","totalCents","receivedQuantity","category","accountCode","createdAt","updatedAt"],"additionalProperties":false}},"approvals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"approverUserId":{"type":"string","format":"uuid"},"decision":{"type":"string"},"decisionAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","approverUserId","decision","decisionAt","notes","createdAt","updatedAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","poNumber","title","description","vendorName","vendorId","status","totalCents","approvedByUserId","approvedAt","fulfilledAt","cancelledAt","cancelledReason","budgetCode","fiscalYear","notes","createdByUserId","lineItems","approvals","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/purchase-orders/{id}/cancel":{"post":{"summary":"Cancel a purchase order","tags":["Purchase Orders"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","nullable":true},"poNumber":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"vendorName":{"type":"string"},"vendorId":{"type":"string","nullable":true},"status":{"type":"string"},"totalCents":{"type":"integer"},"approvedByUserId":{"type":"string","nullable":true},"approvedAt":{"type":"string","format":"date-time","nullable":true},"fulfilledAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"budgetCode":{"type":"string","nullable":true},"fiscalYear":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true},"createdByUserId":{"type":"string","nullable":true},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"description":{"type":"string"},"quantity":{"type":"integer"},"unitCostCents":{"type":"integer"},"totalCents":{"type":"integer"},"receivedQuantity":{"type":"integer"},"category":{"type":"string","nullable":true},"accountCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","sortOrder","description","quantity","unitCostCents","totalCents","receivedQuantity","category","accountCode","createdAt","updatedAt"],"additionalProperties":false}},"approvals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"purchaseOrderId":{"type":"string","format":"uuid"},"approverUserId":{"type":"string","format":"uuid"},"decision":{"type":"string"},"decisionAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","purchaseOrderId","approverUserId","decision","decisionAt","notes","createdAt","updatedAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","poNumber","title","description","vendorName","vendorId","status","totalCents","approvedByUserId","approvedAt","fulfilledAt","cancelledAt","cancelledReason","budgetCode","fiscalYear","notes","createdByUserId","lineItems","approvals","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/pd/activities":{"get":{"summary":"List PD activities","tags":["Professional Development"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"upcoming","required":false},{"schema":{"type":"string","enum":["workshop","conference","course","webinar","coaching","observation","other"]},"in":"query","name":"activityType","required":false},{"schema":{"type":"string","enum":["pd_hours","ceu","graduate_credit","other"]},"in":"query","name":"creditType","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"activityType":{"type":"string"},"provider":{"type":"string","nullable":true},"creditHours":{"type":"string"},"creditType":{"type":"string"},"issuedAt":{"type":"string","format":"date"},"endsAt":{"type":"string","format":"date","nullable":true},"location":{"type":"string","nullable":true},"maxEnrollment":{"type":"integer","nullable":true},"isDistrictSponsored":{"type":"boolean"},"certRenewalCategoryCode":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"enrollmentCount":{"type":"integer"},"completionCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","title","description","activityType","provider","creditHours","creditType","issuedAt","endsAt","location","maxEnrollment","isDistrictSponsored","certRenewalCategoryCode","notes","enrollmentCount","completionCount","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a PD activity","tags":["Professional Development"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":5000},"activityType":{"type":"string","enum":["workshop","conference","course","webinar","coaching","observation","other"]},"provider":{"type":"string","maxLength":200},"creditHours":{"type":"number","minimum":0.1,"maximum":999.9},"creditType":{"type":"string","enum":["pd_hours","ceu","graduate_credit","other"],"default":"pd_hours"},"issuedAt":{"type":"string","format":"date"},"endsAt":{"type":"string","format":"date"},"location":{"type":"string","maxLength":300},"maxEnrollment":{"type":"integer","minimum":1},"isDistrictSponsored":{"type":"boolean","default":false},"certRenewalCategoryCode":{"type":"string","maxLength":60},"notes":{"type":"string","maxLength":10000}},"required":["title","activityType","creditHours","issuedAt"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"activityType":{"type":"string"},"provider":{"type":"string","nullable":true},"creditHours":{"type":"string"},"creditType":{"type":"string"},"issuedAt":{"type":"string","format":"date"},"endsAt":{"type":"string","format":"date","nullable":true},"location":{"type":"string","nullable":true},"maxEnrollment":{"type":"integer","nullable":true},"isDistrictSponsored":{"type":"boolean"},"certRenewalCategoryCode":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"enrollmentCount":{"type":"integer"},"completionCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","title","description","activityType","provider","creditHours","creditType","issuedAt","endsAt","location","maxEnrollment","isDistrictSponsored","certRenewalCategoryCode","notes","enrollmentCount","completionCount","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/pd/activities/{id}":{"get":{"summary":"Get a PD activity with enrollment and completion counts","tags":["Professional Development"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"activityType":{"type":"string"},"provider":{"type":"string","nullable":true},"creditHours":{"type":"string"},"creditType":{"type":"string"},"issuedAt":{"type":"string","format":"date"},"endsAt":{"type":"string","format":"date","nullable":true},"location":{"type":"string","nullable":true},"maxEnrollment":{"type":"integer","nullable":true},"isDistrictSponsored":{"type":"boolean"},"certRenewalCategoryCode":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"enrollmentCount":{"type":"integer"},"completionCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","title","description","activityType","provider","creditHours","creditType","issuedAt","endsAt","location","maxEnrollment","isDistrictSponsored","certRenewalCategoryCode","notes","enrollmentCount","completionCount","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a PD activity","tags":["Professional Development"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":5000,"nullable":true},"activityType":{"type":"string","enum":["workshop","conference","course","webinar","coaching","observation","other"]},"provider":{"type":"string","maxLength":200,"nullable":true},"creditHours":{"type":"number","minimum":0.1,"maximum":999.9},"creditType":{"type":"string","enum":["pd_hours","ceu","graduate_credit","other"]},"issuedAt":{"type":"string","format":"date"},"endsAt":{"type":"string","format":"date","nullable":true},"location":{"type":"string","maxLength":300,"nullable":true},"maxEnrollment":{"type":"integer","minimum":1,"nullable":true},"isDistrictSponsored":{"type":"boolean"},"certRenewalCategoryCode":{"type":"string","maxLength":60,"nullable":true},"notes":{"type":"string","maxLength":10000,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"activityType":{"type":"string"},"provider":{"type":"string","nullable":true},"creditHours":{"type":"string"},"creditType":{"type":"string"},"issuedAt":{"type":"string","format":"date"},"endsAt":{"type":"string","format":"date","nullable":true},"location":{"type":"string","nullable":true},"maxEnrollment":{"type":"integer","nullable":true},"isDistrictSponsored":{"type":"boolean"},"certRenewalCategoryCode":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"enrollmentCount":{"type":"integer"},"completionCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","title","description","activityType","provider","creditHours","creditType","issuedAt","endsAt","location","maxEnrollment","isDistrictSponsored","certRenewalCategoryCode","notes","enrollmentCount","completionCount","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/pd/activities/{id}/enroll":{"post":{"summary":"Enroll a staff member in a PD activity","tags":["Professional Development"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"staffPersonId":{"type":"string","format":"uuid"}},"required":["staffPersonId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"activityId":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"enrolledAt":{"type":"string","format":"date-time"},"status":{"type":"string"},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","activityId","staffPersonId","enrolledAt","status","cancelledAt","cancelledReason","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/pd/activities/{id}/enroll/{staffPersonId}":{"delete":{"summary":"Cancel enrollment for a staff member","tags":["Professional Development"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"staffPersonId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"activityId":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"enrolledAt":{"type":"string","format":"date-time"},"status":{"type":"string"},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"cancelledReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","activityId","staffPersonId","enrolledAt","status","cancelledAt","cancelledReason","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/pd/activities/{id}/complete":{"post":{"summary":"Record completion for a staff member","tags":["Professional Development"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"staffPersonId":{"type":"string","format":"uuid"},"completedAt":{"type":"string","format":"date"},"creditHoursEarned":{"type":"number","minimum":0.1,"maximum":999.9},"certificateUrl":{"type":"string","format":"uri"},"notes":{"type":"string","maxLength":5000}},"required":["staffPersonId","completedAt","creditHoursEarned"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"completion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"activityId":{"type":"string","format":"uuid"},"enrollmentId":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"completedAt":{"type":"string","format":"date"},"creditHoursEarned":{"type":"string"},"certificateUrl":{"type":"string","nullable":true},"verifiedByUserId":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"activityTitle":{"type":"string"},"activityType":{"type":"string"},"creditType":{"type":"string"},"certRenewalCategoryCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","activityId","enrollmentId","staffPersonId","completedAt","creditHoursEarned","certificateUrl","verifiedByUserId","notes","createdAt","updatedAt"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["completion","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/pd/staff/{personId}/history":{"get":{"summary":"All PD completions for a staff member","tags":["Professional Development"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"personId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"activityId":{"type":"string","format":"uuid"},"enrollmentId":{"type":"string","format":"uuid"},"staffPersonId":{"type":"string","format":"uuid"},"completedAt":{"type":"string","format":"date"},"creditHoursEarned":{"type":"string"},"certificateUrl":{"type":"string","nullable":true},"verifiedByUserId":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"activityTitle":{"type":"string"},"activityType":{"type":"string"},"creditType":{"type":"string"},"certRenewalCategoryCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","activityId","enrollmentId","staffPersonId","completedAt","creditHoursEarned","certificateUrl","verifiedByUserId","notes","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/pd/staff/{personId}/credits-summary":{"get":{"summary":"PD credit hour totals by type and cert renewal category for a staff member","tags":["Professional Development"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"personId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"staffPersonId":{"type":"string","format":"uuid"},"totalHours":{"type":"number"},"byType":{"type":"object","additionalProperties":{"type":"number"}},"byCategory":{"type":"object","additionalProperties":{"type":"number"}}},"required":["staffPersonId","totalHours","byType","byCategory"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/volunteers/{personId}/clearances":{"get":{"summary":"List clearances for a volunteer","tags":["Volunteers"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"personId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"clearanceType":{"type":"string"},"issuedAt":{"type":"string","format":"date"},"expiresAt":{"type":"string","format":"date","nullable":true},"status":{"type":"string"},"issuingAgency":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"revokedReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"recordedByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","personId","clearanceType","issuedAt","expiresAt","status","issuingAgency","documentUrl","revokedAt","revokedReason","notes","recordedByUserId","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Record a new clearance for a volunteer","tags":["Volunteers"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"clearanceType":{"type":"string","enum":["criminal_background","child_abuse","sex_offender","drug_test","fingerprint","other"]},"issuedAt":{"type":"string","format":"date"},"expiresAt":{"type":"string","format":"date"},"issuingAgency":{"type":"string","maxLength":200},"documentUrl":{"type":"string","format":"uri","maxLength":500},"notes":{"type":"string","maxLength":5000}},"required":["clearanceType","issuedAt"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"personId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"clearanceType":{"type":"string"},"issuedAt":{"type":"string","format":"date"},"expiresAt":{"type":"string","format":"date","nullable":true},"status":{"type":"string"},"issuingAgency":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"revokedReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"recordedByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","personId","clearanceType","issuedAt","expiresAt","status","issuingAgency","documentUrl","revokedAt","revokedReason","notes","recordedByUserId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/volunteers/clearances/expiring-soon":{"get":{"summary":"List active clearances expiring within 30 days","tags":["Volunteers"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"clearanceType":{"type":"string"},"issuedAt":{"type":"string","format":"date"},"expiresAt":{"type":"string","format":"date","nullable":true},"status":{"type":"string"},"issuingAgency":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"revokedReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"recordedByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","personId","clearanceType","issuedAt","expiresAt","status","issuingAgency","documentUrl","revokedAt","revokedReason","notes","recordedByUserId","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/volunteers/clearances/{id}":{"patch":{"summary":"Update a clearance record","tags":["Volunteers"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"clearanceType":{"type":"string","enum":["criminal_background","child_abuse","sex_offender","drug_test","fingerprint","other"]},"issuedAt":{"type":"string","format":"date"},"expiresAt":{"type":"string","format":"date","nullable":true},"status":{"type":"string","enum":["active","expired","revoked"]},"issuingAgency":{"type":"string","maxLength":200,"nullable":true},"documentUrl":{"type":"string","format":"uri","maxLength":500,"nullable":true},"notes":{"type":"string","maxLength":5000,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"clearanceType":{"type":"string"},"issuedAt":{"type":"string","format":"date"},"expiresAt":{"type":"string","format":"date","nullable":true},"status":{"type":"string"},"issuingAgency":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"revokedReason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"recordedByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","personId","clearanceType","issuedAt","expiresAt","status","issuingAgency","documentUrl","revokedAt","revokedReason","notes","recordedByUserId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/volunteers/clearances/{id}/revoke":{"post":{"summary":"Revoke a volunteer clearance","tags":["Volunteers"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"}},"required":["eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/board/meetings":{"get":{"summary":"List board meetings","tags":["Board"],"parameters":[{"schema":{"type":"string","enum":["scheduled","in_progress","completed","cancelled"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"includeCompleted","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"meetingType":{"type":"string"},"scheduledAt":{"type":"string","format":"date-time"},"location":{"type":"string","nullable":true},"status":{"type":"string"},"videoUrl":{"type":"string","nullable":true},"minutesPublishedAt":{"type":"string","format":"date-time","nullable":true},"agendaItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"meetingId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"presenter":{"type":"string","nullable":true},"estimatedMinutes":{"type":"integer","nullable":true},"actionRequired":{"type":"boolean"},"attachmentUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","meetingId","sortOrder","title","description","presenter","estimatedMinutes","actionRequired","attachmentUrl","createdAt","updatedAt"],"additionalProperties":false}},"minutes":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"meetingId":{"type":"string","format":"uuid"},"minutesText":{"type":"string"},"approvedAt":{"type":"string","format":"date-time","nullable":true},"approvedByUserId":{"type":"string","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","meetingId","minutesText","approvedAt","approvedByUserId","publishedAt","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","title","meetingType","scheduledAt","location","status","videoUrl","minutesPublishedAt","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Schedule a new board meeting","tags":["Board"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"meetingType":{"type":"string","enum":["regular","special","executive_session","emergency"]},"scheduledAt":{"type":"string","format":"date-time"},"location":{"type":"string","maxLength":500},"videoUrl":{"type":"string","format":"uri","maxLength":500}},"required":["title","meetingType","scheduledAt"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"meetingType":{"type":"string"},"scheduledAt":{"type":"string","format":"date-time"},"location":{"type":"string","nullable":true},"status":{"type":"string"},"videoUrl":{"type":"string","nullable":true},"minutesPublishedAt":{"type":"string","format":"date-time","nullable":true},"agendaItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"meetingId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"presenter":{"type":"string","nullable":true},"estimatedMinutes":{"type":"integer","nullable":true},"actionRequired":{"type":"boolean"},"attachmentUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","meetingId","sortOrder","title","description","presenter","estimatedMinutes","actionRequired","attachmentUrl","createdAt","updatedAt"],"additionalProperties":false}},"minutes":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"meetingId":{"type":"string","format":"uuid"},"minutesText":{"type":"string"},"approvedAt":{"type":"string","format":"date-time","nullable":true},"approvedByUserId":{"type":"string","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","meetingId","minutesText","approvedAt","approvedByUserId","publishedAt","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","title","meetingType","scheduledAt","location","status","videoUrl","minutesPublishedAt","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/board/meetings/{id}":{"get":{"summary":"Get a board meeting with agenda items and minutes","tags":["Board"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"meetingType":{"type":"string"},"scheduledAt":{"type":"string","format":"date-time"},"location":{"type":"string","nullable":true},"status":{"type":"string"},"videoUrl":{"type":"string","nullable":true},"minutesPublishedAt":{"type":"string","format":"date-time","nullable":true},"agendaItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"meetingId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"presenter":{"type":"string","nullable":true},"estimatedMinutes":{"type":"integer","nullable":true},"actionRequired":{"type":"boolean"},"attachmentUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","meetingId","sortOrder","title","description","presenter","estimatedMinutes","actionRequired","attachmentUrl","createdAt","updatedAt"],"additionalProperties":false}},"minutes":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"meetingId":{"type":"string","format":"uuid"},"minutesText":{"type":"string"},"approvedAt":{"type":"string","format":"date-time","nullable":true},"approvedByUserId":{"type":"string","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","meetingId","minutesText","approvedAt","approvedByUserId","publishedAt","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","title","meetingType","scheduledAt","location","status","videoUrl","minutesPublishedAt","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a board meeting","tags":["Board"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"meetingType":{"type":"string","enum":["regular","special","executive_session","emergency"]},"scheduledAt":{"type":"string","format":"date-time"},"location":{"type":"string","maxLength":500,"nullable":true},"status":{"type":"string","enum":["scheduled","in_progress","completed","cancelled"]},"videoUrl":{"type":"string","format":"uri","maxLength":500,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"meetingType":{"type":"string"},"scheduledAt":{"type":"string","format":"date-time"},"location":{"type":"string","nullable":true},"status":{"type":"string"},"videoUrl":{"type":"string","nullable":true},"minutesPublishedAt":{"type":"string","format":"date-time","nullable":true},"agendaItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"meetingId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"presenter":{"type":"string","nullable":true},"estimatedMinutes":{"type":"integer","nullable":true},"actionRequired":{"type":"boolean"},"attachmentUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","meetingId","sortOrder","title","description","presenter","estimatedMinutes","actionRequired","attachmentUrl","createdAt","updatedAt"],"additionalProperties":false}},"minutes":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"meetingId":{"type":"string","format":"uuid"},"minutesText":{"type":"string"},"approvedAt":{"type":"string","format":"date-time","nullable":true},"approvedByUserId":{"type":"string","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","meetingId","minutesText","approvedAt","approvedByUserId","publishedAt","createdAt","updatedAt"],"additionalProperties":false,"nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","title","meetingType","scheduledAt","location","status","videoUrl","minutesPublishedAt","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/board/meetings/{id}/agenda":{"post":{"summary":"Add an agenda item to a meeting","tags":["Board"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sortOrder":{"type":"integer","minimum":0},"title":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":5000},"presenter":{"type":"string","maxLength":200},"estimatedMinutes":{"type":"integer","minimum":1},"actionRequired":{"type":"boolean","default":false},"attachmentUrl":{"type":"string","format":"uri","maxLength":500}},"required":["sortOrder","title"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"meetingId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"presenter":{"type":"string","nullable":true},"estimatedMinutes":{"type":"integer","nullable":true},"actionRequired":{"type":"boolean"},"attachmentUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","meetingId","sortOrder","title","description","presenter","estimatedMinutes","actionRequired","attachmentUrl","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/board/meetings/{id}/agenda/{itemId}":{"patch":{"summary":"Update an agenda item","tags":["Board"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sortOrder":{"type":"integer","minimum":0},"title":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":5000,"nullable":true},"presenter":{"type":"string","maxLength":200,"nullable":true},"estimatedMinutes":{"type":"integer","minimum":1,"nullable":true},"actionRequired":{"type":"boolean"},"attachmentUrl":{"type":"string","format":"uri","maxLength":500,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"itemId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"meetingId":{"type":"string","format":"uuid"},"sortOrder":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"presenter":{"type":"string","nullable":true},"estimatedMinutes":{"type":"integer","nullable":true},"actionRequired":{"type":"boolean"},"attachmentUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","meetingId","sortOrder","title","description","presenter","estimatedMinutes","actionRequired","attachmentUrl","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Remove an agenda item","tags":["Board"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"itemId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/board/meetings/{id}/minutes":{"post":{"summary":"Create or update meeting minutes","tags":["Board"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"minutesText":{"type":"string","minLength":1}},"required":["minutesText"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"meetingId":{"type":"string","format":"uuid"},"minutesText":{"type":"string"},"approvedAt":{"type":"string","format":"date-time","nullable":true},"approvedByUserId":{"type":"string","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","meetingId","minutesText","approvedAt","approvedByUserId","publishedAt","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/board/meetings/{id}/publish-minutes":{"post":{"summary":"Publish meeting minutes publicly","tags":["Board"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"}},"required":["eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/public/board/meetings/{districtId}":{"get":{"summary":"Public: upcoming meetings with published minutes for a district","tags":["Board","Public"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":{}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/opra/requests":{"get":{"summary":"List OPRA requests","tags":["OPRA"],"parameters":[{"schema":{"type":"string","enum":["received","in_review","fulfilled","denied","appealed"]},"in":"query","name":"status","required":false},{"schema":{"type":"integer","minimum":1},"in":"query","name":"dueWithin","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"requestorName":{"type":"string"},"requestorEmail":{"type":"string","nullable":true},"requestorPhone":{"type":"string","nullable":true},"requestorAddress":{"type":"string","nullable":true},"description":{"type":"string"},"requestedAt":{"type":"string","format":"date"},"dueAt":{"type":"string","format":"date"},"status":{"type":"string"},"responseUrl":{"type":"string","nullable":true},"responseSentAt":{"type":"string","format":"date-time","nullable":true},"denialReason":{"type":"string","nullable":true},"internalNotes":{"type":"string","nullable":true},"assignedToUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","requestorName","requestorEmail","requestorPhone","requestorAddress","description","requestedAt","dueAt","status","responseUrl","responseSentAt","denialReason","internalNotes","assignedToUserId","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Record a new OPRA request (auto-computes 7-business-day deadline)","tags":["OPRA"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"requestorName":{"type":"string","minLength":1,"maxLength":200},"requestorEmail":{"type":"string","format":"email","maxLength":200},"requestorPhone":{"type":"string","maxLength":30},"requestorAddress":{"type":"string","maxLength":500},"description":{"type":"string","minLength":1},"requestedAt":{"type":"string","format":"date"}},"required":["requestorName","description","requestedAt"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"requestorName":{"type":"string"},"requestorEmail":{"type":"string","nullable":true},"requestorPhone":{"type":"string","nullable":true},"requestorAddress":{"type":"string","nullable":true},"description":{"type":"string"},"requestedAt":{"type":"string","format":"date"},"dueAt":{"type":"string","format":"date"},"status":{"type":"string"},"responseUrl":{"type":"string","nullable":true},"responseSentAt":{"type":"string","format":"date-time","nullable":true},"denialReason":{"type":"string","nullable":true},"internalNotes":{"type":"string","nullable":true},"assignedToUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","requestorName","requestorEmail","requestorPhone","requestorAddress","description","requestedAt","dueAt","status","responseUrl","responseSentAt","denialReason","internalNotes","assignedToUserId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/opra/requests/overdue":{"get":{"summary":"List overdue OPRA requests (past due date, not fulfilled or denied)","tags":["OPRA"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"requestorName":{"type":"string"},"requestorEmail":{"type":"string","nullable":true},"requestorPhone":{"type":"string","nullable":true},"requestorAddress":{"type":"string","nullable":true},"description":{"type":"string"},"requestedAt":{"type":"string","format":"date"},"dueAt":{"type":"string","format":"date"},"status":{"type":"string"},"responseUrl":{"type":"string","nullable":true},"responseSentAt":{"type":"string","format":"date-time","nullable":true},"denialReason":{"type":"string","nullable":true},"internalNotes":{"type":"string","nullable":true},"assignedToUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","requestorName","requestorEmail","requestorPhone","requestorAddress","description","requestedAt","dueAt","status","responseUrl","responseSentAt","denialReason","internalNotes","assignedToUserId","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/opra/requests/{id}":{"get":{"summary":"Get a single OPRA request","tags":["OPRA"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"requestorName":{"type":"string"},"requestorEmail":{"type":"string","nullable":true},"requestorPhone":{"type":"string","nullable":true},"requestorAddress":{"type":"string","nullable":true},"description":{"type":"string"},"requestedAt":{"type":"string","format":"date"},"dueAt":{"type":"string","format":"date"},"status":{"type":"string"},"responseUrl":{"type":"string","nullable":true},"responseSentAt":{"type":"string","format":"date-time","nullable":true},"denialReason":{"type":"string","nullable":true},"internalNotes":{"type":"string","nullable":true},"assignedToUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","requestorName","requestorEmail","requestorPhone","requestorAddress","description","requestedAt","dueAt","status","responseUrl","responseSentAt","denialReason","internalNotes","assignedToUserId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update an OPRA request status, response, notes, or assignment","tags":["OPRA"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["received","in_review","fulfilled","denied","appealed"]},"responseUrl":{"type":"string","format":"uri","maxLength":500,"nullable":true},"responseSentAt":{"type":"string","format":"date-time","nullable":true},"denialReason":{"type":"string","maxLength":500,"nullable":true},"internalNotes":{"type":"string","nullable":true},"assignedToUserId":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"requestorName":{"type":"string"},"requestorEmail":{"type":"string","nullable":true},"requestorPhone":{"type":"string","nullable":true},"requestorAddress":{"type":"string","nullable":true},"description":{"type":"string"},"requestedAt":{"type":"string","format":"date"},"dueAt":{"type":"string","format":"date"},"status":{"type":"string"},"responseUrl":{"type":"string","nullable":true},"responseSentAt":{"type":"string","format":"date-time","nullable":true},"denialReason":{"type":"string","nullable":true},"internalNotes":{"type":"string","nullable":true},"assignedToUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","requestorName","requestorEmail","requestorPhone","requestorAddress","description","requestedAt","dueAt","status","responseUrl","responseSentAt","denialReason","internalNotes","assignedToUserId","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/child-find/referrals":{"get":{"summary":"List Child Find referrals","tags":["ChildFind"],"parameters":[{"schema":{"type":"string","enum":["pending","eligible","not_eligible","evaluation_in_progress"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"evaluationDueSoon","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"referredPersonId":{"type":"string","format":"uuid"},"referralDate":{"type":"string","format":"date"},"referralSource":{"type":"string"},"referralReason":{"type":"string"},"dateOfBirth":{"type":"string","format":"date"},"ageAtReferral":{"type":"integer"},"eligibilityStatus":{"type":"string"},"eligibilityDeterminedAt":{"type":"string","format":"date-time","nullable":true},"eligibilityNotes":{"type":"string","nullable":true},"iepCreatedFromReferral":{"type":"boolean"},"iepId":{"type":"string","nullable":true},"assignedEvaluatorId":{"type":"string","nullable":true},"evaluationDueAt":{"type":"string","format":"date","nullable":true},"outcomeNotes":{"type":"string","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","referredPersonId","referralDate","referralSource","referralReason","dateOfBirth","ageAtReferral","eligibilityStatus","eligibilityDeterminedAt","eligibilityNotes","iepCreatedFromReferral","iepId","assignedEvaluatorId","evaluationDueAt","outcomeNotes","closedAt","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Record a new Child Find referral (validates IDEA age window)","tags":["ChildFind"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"referredPersonId":{"type":"string","format":"uuid"},"referralDate":{"type":"string","format":"date"},"referralSource":{"type":"string","enum":["parent","teacher","physician","self_referral","community","other"]},"referralReason":{"type":"string","minLength":1},"dateOfBirth":{"type":"string","format":"date"},"assignedEvaluatorId":{"type":"string","format":"uuid"}},"required":["referredPersonId","referralDate","referralSource","referralReason","dateOfBirth"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"referredPersonId":{"type":"string","format":"uuid"},"referralDate":{"type":"string","format":"date"},"referralSource":{"type":"string"},"referralReason":{"type":"string"},"dateOfBirth":{"type":"string","format":"date"},"ageAtReferral":{"type":"integer"},"eligibilityStatus":{"type":"string"},"eligibilityDeterminedAt":{"type":"string","format":"date-time","nullable":true},"eligibilityNotes":{"type":"string","nullable":true},"iepCreatedFromReferral":{"type":"boolean"},"iepId":{"type":"string","nullable":true},"assignedEvaluatorId":{"type":"string","nullable":true},"evaluationDueAt":{"type":"string","format":"date","nullable":true},"outcomeNotes":{"type":"string","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","referredPersonId","referralDate","referralSource","referralReason","dateOfBirth","ageAtReferral","eligibilityStatus","eligibilityDeterminedAt","eligibilityNotes","iepCreatedFromReferral","iepId","assignedEvaluatorId","evaluationDueAt","outcomeNotes","closedAt","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/child-find/referrals/evaluation-due-soon":{"get":{"summary":"List referrals with evaluation deadlines within 14 days","tags":["ChildFind"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"referredPersonId":{"type":"string","format":"uuid"},"referralDate":{"type":"string","format":"date"},"referralSource":{"type":"string"},"referralReason":{"type":"string"},"dateOfBirth":{"type":"string","format":"date"},"ageAtReferral":{"type":"integer"},"eligibilityStatus":{"type":"string"},"eligibilityDeterminedAt":{"type":"string","format":"date-time","nullable":true},"eligibilityNotes":{"type":"string","nullable":true},"iepCreatedFromReferral":{"type":"boolean"},"iepId":{"type":"string","nullable":true},"assignedEvaluatorId":{"type":"string","nullable":true},"evaluationDueAt":{"type":"string","format":"date","nullable":true},"outcomeNotes":{"type":"string","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","referredPersonId","referralDate","referralSource","referralReason","dateOfBirth","ageAtReferral","eligibilityStatus","eligibilityDeterminedAt","eligibilityNotes","iepCreatedFromReferral","iepId","assignedEvaluatorId","evaluationDueAt","outcomeNotes","closedAt","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/child-find/referrals/{id}":{"get":{"summary":"Get a Child Find referral","tags":["ChildFind"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"referredPersonId":{"type":"string","format":"uuid"},"referralDate":{"type":"string","format":"date"},"referralSource":{"type":"string"},"referralReason":{"type":"string"},"dateOfBirth":{"type":"string","format":"date"},"ageAtReferral":{"type":"integer"},"eligibilityStatus":{"type":"string"},"eligibilityDeterminedAt":{"type":"string","format":"date-time","nullable":true},"eligibilityNotes":{"type":"string","nullable":true},"iepCreatedFromReferral":{"type":"boolean"},"iepId":{"type":"string","nullable":true},"assignedEvaluatorId":{"type":"string","nullable":true},"evaluationDueAt":{"type":"string","format":"date","nullable":true},"outcomeNotes":{"type":"string","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","referredPersonId","referralDate","referralSource","referralReason","dateOfBirth","ageAtReferral","eligibilityStatus","eligibilityDeterminedAt","eligibilityNotes","iepCreatedFromReferral","iepId","assignedEvaluatorId","evaluationDueAt","outcomeNotes","closedAt","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a Child Find referral","tags":["ChildFind"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"eligibilityStatus":{"type":"string","enum":["pending","eligible","not_eligible","evaluation_in_progress"]},"eligibilityNotes":{"type":"string","nullable":true},"assignedEvaluatorId":{"type":"string","format":"uuid","nullable":true},"outcomeNotes":{"type":"string","nullable":true},"referralReason":{"type":"string"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"referredPersonId":{"type":"string","format":"uuid"},"referralDate":{"type":"string","format":"date"},"referralSource":{"type":"string"},"referralReason":{"type":"string"},"dateOfBirth":{"type":"string","format":"date"},"ageAtReferral":{"type":"integer"},"eligibilityStatus":{"type":"string"},"eligibilityDeterminedAt":{"type":"string","format":"date-time","nullable":true},"eligibilityNotes":{"type":"string","nullable":true},"iepCreatedFromReferral":{"type":"boolean"},"iepId":{"type":"string","nullable":true},"assignedEvaluatorId":{"type":"string","nullable":true},"evaluationDueAt":{"type":"string","format":"date","nullable":true},"outcomeNotes":{"type":"string","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","referredPersonId","referralDate","referralSource","referralReason","dateOfBirth","ageAtReferral","eligibilityStatus","eligibilityDeterminedAt","eligibilityNotes","iepCreatedFromReferral","iepId","assignedEvaluatorId","evaluationDueAt","outcomeNotes","closedAt","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/child-find/referrals/{id}/determine-eligibility":{"post":{"summary":"Record eligibility determination for a referral","tags":["ChildFind"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"eligibilityStatus":{"type":"string","enum":["pending","eligible","not_eligible","evaluation_in_progress"]},"notes":{"type":"string"}},"required":["eligibilityStatus"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"}},"required":["eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/child-find/referrals/{id}/create-iep":{"post":{"summary":"Mark IEP as created from this referral","tags":["ChildFind"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"iepId":{"type":"string","format":"uuid"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"referredPersonId":{"type":"string","format":"uuid"},"referralDate":{"type":"string","format":"date"},"referralSource":{"type":"string"},"referralReason":{"type":"string"},"dateOfBirth":{"type":"string","format":"date"},"ageAtReferral":{"type":"integer"},"eligibilityStatus":{"type":"string"},"eligibilityDeterminedAt":{"type":"string","format":"date-time","nullable":true},"eligibilityNotes":{"type":"string","nullable":true},"iepCreatedFromReferral":{"type":"boolean"},"iepId":{"type":"string","nullable":true},"assignedEvaluatorId":{"type":"string","nullable":true},"evaluationDueAt":{"type":"string","format":"date","nullable":true},"outcomeNotes":{"type":"string","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","referredPersonId","referralDate","referralSource","referralReason","dateOfBirth","ageAtReferral","eligibilityStatus","eligibilityDeterminedAt","eligibilityNotes","iepCreatedFromReferral","iepId","assignedEvaluatorId","evaluationDueAt","outcomeNotes","closedAt","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/visitor/kiosk-info":{"get":{"summary":"Return district/school branding for the public kiosk","tags":["Visitor"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"districtId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"districtId":{"type":"string","format":"uuid"},"districtName":{"type":"string"},"schoolId":{"type":"string","format":"uuid","nullable":true},"schoolName":{"type":"string","nullable":true}},"required":["districtId","districtName","schoolId","schoolName"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/visitor/check-in":{"post":{"summary":"Check a visitor in (emits VisitorCheckedIn)","tags":["Visitor"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid"},"visitorName":{"type":"string","minLength":1,"maxLength":200},"visitorCompany":{"type":"string","maxLength":200},"visitorPhone":{"type":"string","maxLength":30},"visitorEmail":{"type":"string","format":"email","maxLength":200},"visitorIdType":{"type":"string","enum":["DRIVERS_LICENSE","PASSPORT","OTHER"]},"visitorIdNumber":{"type":"string","maxLength":100},"purpose":{"type":"string","enum":["STUDENT_PICKUP","MEETING","VOLUNTEER","CONTRACTOR","OTHER"]},"purposeNotes":{"type":"string","maxLength":500},"hostPersonId":{"type":"string","format":"uuid"},"studentPersonId":{"type":"string","format":"uuid"},"skipSexOffenderCheck":{"type":"boolean","default":false},"visitorDateOfBirth":{"type":"string","format":"date"},"visitorState":{"type":"string","minLength":2,"maxLength":2},"visitorAliases":{"type":"array","items":{"type":"string","maxLength":200},"maxItems":10}},"required":["visitorName","purpose"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"visitor":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"visitorName":{"type":"string"},"visitorCompany":{"type":"string","nullable":true},"visitorPhone":{"type":"string","nullable":true},"visitorEmail":{"type":"string","nullable":true},"visitorIdType":{"type":"string","nullable":true},"purpose":{"type":"string"},"purposeNotes":{"type":"string","nullable":true},"hostPersonId":{"type":"string","format":"uuid","nullable":true},"studentPersonId":{"type":"string","format":"uuid","nullable":true},"checkInAt":{"type":"string","format":"date-time"},"checkOutAt":{"type":"string","format":"date-time","nullable":true},"badgeNumber":{"type":"string","nullable":true},"sexOffenderCheckStatus":{"type":"string"},"sexOffenderCheckAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string"},"denialReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","visitorName","visitorCompany","visitorPhone","visitorEmail","visitorIdType","purpose","purposeNotes","hostPersonId","studentPersonId","checkInAt","checkOutAt","badgeNumber","sexOffenderCheckStatus","sexOffenderCheckAt","status","denialReason","createdAt","updatedAt"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["visitor","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/visitor/active":{"get":{"summary":"List visitors currently checked in","tags":["Visitor"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"visitorName":{"type":"string"},"visitorCompany":{"type":"string","nullable":true},"visitorPhone":{"type":"string","nullable":true},"visitorEmail":{"type":"string","nullable":true},"visitorIdType":{"type":"string","nullable":true},"purpose":{"type":"string"},"purposeNotes":{"type":"string","nullable":true},"hostPersonId":{"type":"string","format":"uuid","nullable":true},"studentPersonId":{"type":"string","format":"uuid","nullable":true},"checkInAt":{"type":"string","format":"date-time"},"checkOutAt":{"type":"string","format":"date-time","nullable":true},"badgeNumber":{"type":"string","nullable":true},"sexOffenderCheckStatus":{"type":"string"},"sexOffenderCheckAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string"},"denialReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","visitorName","visitorCompany","visitorPhone","visitorEmail","visitorIdType","purpose","purposeNotes","hostPersonId","studentPersonId","checkInAt","checkOutAt","badgeNumber","sexOffenderCheckStatus","sexOffenderCheckAt","status","denialReason","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/visitor":{"get":{"summary":"List visitor log entries (paginated)","tags":["Visitor"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["CHECKED_IN","CHECKED_OUT","DENIED"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"schoolId","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"to","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"visitorName":{"type":"string"},"visitorCompany":{"type":"string","nullable":true},"visitorPhone":{"type":"string","nullable":true},"visitorEmail":{"type":"string","nullable":true},"visitorIdType":{"type":"string","nullable":true},"purpose":{"type":"string"},"purposeNotes":{"type":"string","nullable":true},"hostPersonId":{"type":"string","format":"uuid","nullable":true},"studentPersonId":{"type":"string","format":"uuid","nullable":true},"checkInAt":{"type":"string","format":"date-time"},"checkOutAt":{"type":"string","format":"date-time","nullable":true},"badgeNumber":{"type":"string","nullable":true},"sexOffenderCheckStatus":{"type":"string"},"sexOffenderCheckAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string"},"denialReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","visitorName","visitorCompany","visitorPhone","visitorEmail","visitorIdType","purpose","purposeNotes","hostPersonId","studentPersonId","checkInAt","checkOutAt","badgeNumber","sexOffenderCheckStatus","sexOffenderCheckAt","status","denialReason","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/visitor/{id}":{"get":{"summary":"Get a single visitor log entry","tags":["Visitor"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"visitor":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"visitorName":{"type":"string"},"visitorCompany":{"type":"string","nullable":true},"visitorPhone":{"type":"string","nullable":true},"visitorEmail":{"type":"string","nullable":true},"visitorIdType":{"type":"string","nullable":true},"purpose":{"type":"string"},"purposeNotes":{"type":"string","nullable":true},"hostPersonId":{"type":"string","format":"uuid","nullable":true},"studentPersonId":{"type":"string","format":"uuid","nullable":true},"checkInAt":{"type":"string","format":"date-time"},"checkOutAt":{"type":"string","format":"date-time","nullable":true},"badgeNumber":{"type":"string","nullable":true},"sexOffenderCheckStatus":{"type":"string"},"sexOffenderCheckAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string"},"denialReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","visitorName","visitorCompany","visitorPhone","visitorEmail","visitorIdType","purpose","purposeNotes","hostPersonId","studentPersonId","checkInAt","checkOutAt","badgeNumber","sexOffenderCheckStatus","sexOffenderCheckAt","status","denialReason","createdAt","updatedAt"],"additionalProperties":false}},"required":["visitor"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Permanently delete a visitor log entry (emits VisitorDeleted)","tags":["Visitor"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventId":{"type":"string","format":"uuid"}},"required":["id","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/visitor/{id}/check-out":{"post":{"summary":"Check a visitor out (emits VisitorCheckedOut)","tags":["Visitor"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"visitor":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"visitorName":{"type":"string"},"visitorCompany":{"type":"string","nullable":true},"visitorPhone":{"type":"string","nullable":true},"visitorEmail":{"type":"string","nullable":true},"visitorIdType":{"type":"string","nullable":true},"purpose":{"type":"string"},"purposeNotes":{"type":"string","nullable":true},"hostPersonId":{"type":"string","format":"uuid","nullable":true},"studentPersonId":{"type":"string","format":"uuid","nullable":true},"checkInAt":{"type":"string","format":"date-time"},"checkOutAt":{"type":"string","format":"date-time","nullable":true},"badgeNumber":{"type":"string","nullable":true},"sexOffenderCheckStatus":{"type":"string"},"sexOffenderCheckAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string"},"denialReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","visitorName","visitorCompany","visitorPhone","visitorEmail","visitorIdType","purpose","purposeNotes","hostPersonId","studentPersonId","checkInAt","checkOutAt","badgeNumber","sexOffenderCheckStatus","sexOffenderCheckAt","status","denialReason","createdAt","updatedAt"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["visitor","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/visitor/{id}/deny":{"post":{"summary":"Deny a visitor entry (emits VisitorDenied)","tags":["Visitor"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"denialReason":{"type":"string","minLength":1,"maxLength":500}},"required":["denialReason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"visitor":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","format":"uuid","nullable":true},"visitorName":{"type":"string"},"visitorCompany":{"type":"string","nullable":true},"visitorPhone":{"type":"string","nullable":true},"visitorEmail":{"type":"string","nullable":true},"visitorIdType":{"type":"string","nullable":true},"purpose":{"type":"string"},"purposeNotes":{"type":"string","nullable":true},"hostPersonId":{"type":"string","format":"uuid","nullable":true},"studentPersonId":{"type":"string","format":"uuid","nullable":true},"checkInAt":{"type":"string","format":"date-time"},"checkOutAt":{"type":"string","format":"date-time","nullable":true},"badgeNumber":{"type":"string","nullable":true},"sexOffenderCheckStatus":{"type":"string"},"sexOffenderCheckAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string"},"denialReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","visitorName","visitorCompany","visitorPhone","visitorEmail","visitorIdType","purpose","purposeNotes","hostPersonId","studentPersonId","checkInAt","checkOutAt","badgeNumber","sexOffenderCheckStatus","sexOffenderCheckAt","status","denialReason","createdAt","updatedAt"],"additionalProperties":false},"eventId":{"type":"string","format":"uuid"}},"required":["visitor","eventId"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/surveys":{"get":{"summary":"List surveys with response counts","tags":["Surveys"],"parameters":[{"schema":{"type":"string","enum":["DRAFT","ACTIVE","CLOSED"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["STUDENT","PARENT","STAFF","ALL"]},"in":"query","name":"audience","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"audience":{"type":"string"},"status":{"type":"string"},"opensAt":{"type":"string","format":"date-time","nullable":true},"closesAt":{"type":"string","format":"date-time","nullable":true},"schoolYearId":{"type":"string","nullable":true},"isAnonymous":{"type":"boolean"},"allowMultipleResponses":{"type":"boolean"},"createdByPersonId":{"type":"string"},"responseCount":{"type":"integer"},"questionCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","title","description","audience","status","opensAt","closesAt","schoolYearId","isAnonymous","allowMultipleResponses","createdByPersonId","responseCount","questionCount","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a survey (status = DRAFT)","tags":["Surveys"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":10000},"audience":{"type":"string","enum":["STUDENT","PARENT","STAFF","ALL"]},"opensAt":{"type":"string","format":"date-time"},"closesAt":{"type":"string","format":"date-time"},"schoolYearId":{"type":"string","format":"uuid"},"isAnonymous":{"type":"boolean","default":false},"allowMultipleResponses":{"type":"boolean","default":false},"createdByPersonId":{"type":"string","format":"uuid"}},"required":["title","audience"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"audience":{"type":"string"},"status":{"type":"string"},"opensAt":{"type":"string","format":"date-time","nullable":true},"closesAt":{"type":"string","format":"date-time","nullable":true},"schoolYearId":{"type":"string","nullable":true},"isAnonymous":{"type":"boolean"},"allowMultipleResponses":{"type":"boolean"},"createdByPersonId":{"type":"string"},"responseCount":{"type":"integer"},"questionCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"surveyId":{"type":"string","format":"uuid"},"orderIndex":{"type":"integer"},"questionText":{"type":"string"},"questionType":{"type":"string"},"options":{"type":"array","items":{"type":"string"},"nullable":true},"isRequired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","surveyId","orderIndex","questionText","questionType","options","isRequired","createdAt","updatedAt"],"additionalProperties":false}}},"required":["id","districtId","title","description","audience","status","opensAt","closesAt","schoolYearId","isAnonymous","allowMultipleResponses","createdByPersonId","responseCount","questionCount","createdAt","updatedAt","questions"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/surveys/{id}":{"get":{"summary":"Get a survey with its questions","tags":["Surveys"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"audience":{"type":"string"},"status":{"type":"string"},"opensAt":{"type":"string","format":"date-time","nullable":true},"closesAt":{"type":"string","format":"date-time","nullable":true},"schoolYearId":{"type":"string","nullable":true},"isAnonymous":{"type":"boolean"},"allowMultipleResponses":{"type":"boolean"},"createdByPersonId":{"type":"string"},"responseCount":{"type":"integer"},"questionCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"surveyId":{"type":"string","format":"uuid"},"orderIndex":{"type":"integer"},"questionText":{"type":"string"},"questionType":{"type":"string"},"options":{"type":"array","items":{"type":"string"},"nullable":true},"isRequired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","surveyId","orderIndex","questionText","questionType","options","isRequired","createdAt","updatedAt"],"additionalProperties":false}}},"required":["id","districtId","title","description","audience","status","opensAt","closesAt","schoolYearId","isAnonymous","allowMultipleResponses","createdByPersonId","responseCount","questionCount","createdAt","updatedAt","questions"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a survey (active surveys: only dates may change)","tags":["Surveys"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":10000},"opensAt":{"type":"string","format":"date-time","nullable":true},"closesAt":{"type":"string","format":"date-time","nullable":true},"schoolYearId":{"type":"string","format":"uuid","nullable":true},"isAnonymous":{"type":"boolean"},"allowMultipleResponses":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"audience":{"type":"string"},"status":{"type":"string"},"opensAt":{"type":"string","format":"date-time","nullable":true},"closesAt":{"type":"string","format":"date-time","nullable":true},"schoolYearId":{"type":"string","nullable":true},"isAnonymous":{"type":"boolean"},"allowMultipleResponses":{"type":"boolean"},"createdByPersonId":{"type":"string"},"responseCount":{"type":"integer"},"questionCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"surveyId":{"type":"string","format":"uuid"},"orderIndex":{"type":"integer"},"questionText":{"type":"string"},"questionType":{"type":"string"},"options":{"type":"array","items":{"type":"string"},"nullable":true},"isRequired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","surveyId","orderIndex","questionText","questionType","options","isRequired","createdAt","updatedAt"],"additionalProperties":false}}},"required":["id","districtId","title","description","audience","status","opensAt","closesAt","schoolYearId","isAnonymous","allowMultipleResponses","createdByPersonId","responseCount","questionCount","createdAt","updatedAt","questions"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a DRAFT survey (hard delete — only if 0 responses)","tags":["Surveys"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response","content":{"application/json":{"schema":{"enum":["null"],"nullable":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/surveys/{id}/publish":{"post":{"summary":"Publish a survey (must have ≥1 question)","tags":["Surveys"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"audience":{"type":"string"},"status":{"type":"string"},"opensAt":{"type":"string","format":"date-time","nullable":true},"closesAt":{"type":"string","format":"date-time","nullable":true},"schoolYearId":{"type":"string","nullable":true},"isAnonymous":{"type":"boolean"},"allowMultipleResponses":{"type":"boolean"},"createdByPersonId":{"type":"string"},"responseCount":{"type":"integer"},"questionCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"surveyId":{"type":"string","format":"uuid"},"orderIndex":{"type":"integer"},"questionText":{"type":"string"},"questionType":{"type":"string"},"options":{"type":"array","items":{"type":"string"},"nullable":true},"isRequired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","surveyId","orderIndex","questionText","questionType","options","isRequired","createdAt","updatedAt"],"additionalProperties":false}}},"required":["id","districtId","title","description","audience","status","opensAt","closesAt","schoolYearId","isAnonymous","allowMultipleResponses","createdByPersonId","responseCount","questionCount","createdAt","updatedAt","questions"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/surveys/{id}/close":{"post":{"summary":"Close a survey","tags":["Surveys"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"audience":{"type":"string"},"status":{"type":"string"},"opensAt":{"type":"string","format":"date-time","nullable":true},"closesAt":{"type":"string","format":"date-time","nullable":true},"schoolYearId":{"type":"string","nullable":true},"isAnonymous":{"type":"boolean"},"allowMultipleResponses":{"type":"boolean"},"createdByPersonId":{"type":"string"},"responseCount":{"type":"integer"},"questionCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"surveyId":{"type":"string","format":"uuid"},"orderIndex":{"type":"integer"},"questionText":{"type":"string"},"questionType":{"type":"string"},"options":{"type":"array","items":{"type":"string"},"nullable":true},"isRequired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","surveyId","orderIndex","questionText","questionType","options","isRequired","createdAt","updatedAt"],"additionalProperties":false}}},"required":["id","districtId","title","description","audience","status","opensAt","closesAt","schoolYearId","isAnonymous","allowMultipleResponses","createdByPersonId","responseCount","questionCount","createdAt","updatedAt","questions"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/surveys/{id}/questions":{"post":{"summary":"Add a question to a survey","tags":["Surveys"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"questionText":{"type":"string","minLength":1,"maxLength":2000},"questionType":{"type":"string","enum":["TEXT","MULTIPLE_CHOICE","RATING_1_5","RATING_1_10","YES_NO","CHECKBOX"]},"orderIndex":{"type":"integer","minimum":0,"default":0},"options":{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":50},"isRequired":{"type":"boolean","default":false}},"required":["questionText","questionType"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"surveyId":{"type":"string","format":"uuid"},"orderIndex":{"type":"integer"},"questionText":{"type":"string"},"questionType":{"type":"string"},"options":{"type":"array","items":{"type":"string"},"nullable":true},"isRequired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","surveyId","orderIndex","questionText","questionType","options","isRequired","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/surveys/{id}/questions/{qid}":{"patch":{"summary":"Update a survey question","tags":["Surveys"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"questionText":{"type":"string","minLength":1,"maxLength":2000},"questionType":{"type":"string","enum":["TEXT","MULTIPLE_CHOICE","RATING_1_5","RATING_1_10","YES_NO","CHECKBOX"]},"orderIndex":{"type":"integer","minimum":0},"options":{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":50,"nullable":true},"isRequired":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"qid","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"surveyId":{"type":"string","format":"uuid"},"orderIndex":{"type":"integer"},"questionText":{"type":"string"},"questionType":{"type":"string"},"options":{"type":"array","items":{"type":"string"},"nullable":true},"isRequired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","surveyId","orderIndex","questionText","questionType","options","isRequired","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a question (only on DRAFT surveys)","tags":["Surveys"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"qid","required":true}],"responses":{"204":{"description":"Default Response","content":{"application/json":{"schema":{"enum":["null"],"nullable":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/surveys/respond-eligible":{"get":{"summary":"List active surveys the calling user can respond to","tags":["Surveys"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"audience":{"type":"string"},"status":{"type":"string"},"opensAt":{"type":"string","format":"date-time","nullable":true},"closesAt":{"type":"string","format":"date-time","nullable":true},"schoolYearId":{"type":"string","nullable":true},"isAnonymous":{"type":"boolean"},"allowMultipleResponses":{"type":"boolean"},"createdByPersonId":{"type":"string"},"responseCount":{"type":"integer"},"questionCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","title","description","audience","status","opensAt","closesAt","schoolYearId","isAnonymous","allowMultipleResponses","createdByPersonId","responseCount","questionCount","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/surveys/{id}/respond":{"get":{"summary":"Get survey questions for responding (audience-gated)","tags":["Surveys"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"audience":{"type":"string"},"status":{"type":"string"},"opensAt":{"type":"string","format":"date-time","nullable":true},"closesAt":{"type":"string","format":"date-time","nullable":true},"schoolYearId":{"type":"string","nullable":true},"isAnonymous":{"type":"boolean"},"allowMultipleResponses":{"type":"boolean"},"createdByPersonId":{"type":"string"},"responseCount":{"type":"integer"},"questionCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"surveyId":{"type":"string","format":"uuid"},"orderIndex":{"type":"integer"},"questionText":{"type":"string"},"questionType":{"type":"string"},"options":{"type":"array","items":{"type":"string"},"nullable":true},"isRequired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","surveyId","orderIndex","questionText","questionType","options","isRequired","createdAt","updatedAt"],"additionalProperties":false}}},"required":["id","districtId","title","description","audience","status","opensAt","closesAt","schoolYearId","isAnonymous","allowMultipleResponses","createdByPersonId","responseCount","questionCount","createdAt","updatedAt","questions"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/surveys/{id}/responses":{"post":{"summary":"Submit a survey response","tags":["Surveys"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"respondentType":{"type":"string","enum":["STUDENT","PARENT","STAFF"]},"answers":{"type":"array","items":{"type":"object","properties":{"questionId":{"type":"string","format":"uuid"},"answerText":{"type":"string","maxLength":10000},"answerNumber":{"type":"integer"},"answerBoolean":{"type":"boolean"},"answerOptions":{"type":"array","items":{"type":"string"}}},"required":["questionId"],"additionalProperties":false},"minItems":1,"maxItems":200}},"required":["respondentType","answers"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"surveyId":{"type":"string","format":"uuid"},"respondentPersonId":{"type":"string","nullable":true},"respondentType":{"type":"string"},"submittedAt":{"type":"string","format":"date-time"}},"required":["id","surveyId","respondentPersonId","respondentType","submittedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"get":{"summary":"List individual responses (admin only)","tags":["Surveys"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"surveyId":{"type":"string","format":"uuid"},"respondentPersonId":{"type":"string","nullable":true},"respondentType":{"type":"string"},"submittedAt":{"type":"string","format":"date-time"}},"required":["id","surveyId","respondentPersonId","respondentType","submittedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/surveys/{id}/results":{"get":{"summary":"Aggregate results by question","tags":["Surveys"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"surveyId":{"type":"string","format":"uuid"},"totalResponses":{"type":"integer"},"questionResults":{"type":"array","items":{"type":"object","properties":{"question":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"surveyId":{"type":"string","format":"uuid"},"orderIndex":{"type":"integer"},"questionText":{"type":"string"},"questionType":{"type":"string"},"options":{"type":"array","items":{"type":"string"},"nullable":true},"isRequired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","surveyId","orderIndex","questionText","questionType","options","isRequired","createdAt","updatedAt"],"additionalProperties":false},"answeredCount":{"type":"integer"},"result":{"anyOf":[{"type":"object","properties":{"questionType":{"type":"string","enum":["TEXT"]},"sampleAnswers":{"type":"array","items":{"type":"string"}}},"required":["questionType","sampleAnswers"],"additionalProperties":false},{"type":"object","properties":{"questionType":{"anyOf":[{"type":"string","enum":["RATING_1_5"]},{"type":"string","enum":["RATING_1_10"]}]},"average":{"type":"number"},"min":{"type":"number"},"max":{"type":"number"},"distribution":{"type":"object","additionalProperties":{"type":"number"}}},"required":["questionType","average","min","max","distribution"],"additionalProperties":false},{"type":"object","properties":{"questionType":{"anyOf":[{"type":"string","enum":["MULTIPLE_CHOICE"]},{"type":"string","enum":["CHECKBOX"]}]},"counts":{"type":"object","additionalProperties":{"type":"number"}}},"required":["questionType","counts"],"additionalProperties":false},{"type":"object","properties":{"questionType":{"type":"string","enum":["YES_NO"]},"yesCount":{"type":"integer"},"noCount":{"type":"integer"},"yesPct":{"type":"number"},"noPct":{"type":"number"}},"required":["questionType","yesCount","noCount","yesPct","noPct"],"additionalProperties":false}]}},"required":["question","answeredCount","result"],"additionalProperties":false}}},"required":["surveyId","totalResponses","questionResults"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/templates":{"get":{"summary":"List available website templates","tags":["Websites"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"previewImageUrl":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"config":{"type":"object","additionalProperties":{}}},"required":["id","name","description","previewImageUrl","isActive","config"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites":{"get":{"summary":"List sites for this district","tags":["Websites"],"parameters":[{"schema":{"type":"string","enum":["DISTRICT","SCHOOL"]},"in":"query","name":"type","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","nullable":true},"type":{"type":"string","enum":["DISTRICT","SCHOOL"]},"name":{"type":"string"},"slug":{"type":"string"},"templateId":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PUBLISHED","ARCHIVED"]},"previewSlug":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","type","name","slug","templateId","status","previewSlug","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a site","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["DISTRICT","SCHOOL"]},"name":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9-]+$"},"schoolId":{"type":"string","format":"uuid"},"templateId":{"type":"string","format":"uuid"}},"required":["type","name","slug"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","nullable":true},"type":{"type":"string","enum":["DISTRICT","SCHOOL"]},"name":{"type":"string"},"slug":{"type":"string"},"templateId":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PUBLISHED","ARCHIVED"]},"previewSlug":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","type","name","slug","templateId","status","previewSlug","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}":{"get":{"summary":"Get a site","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","nullable":true},"type":{"type":"string","enum":["DISTRICT","SCHOOL"]},"name":{"type":"string"},"slug":{"type":"string"},"templateId":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PUBLISHED","ARCHIVED"]},"previewSlug":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","type","name","slug","templateId","status","previewSlug","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a site","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"templateId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["DRAFT","PUBLISHED","ARCHIVED"]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"schoolId":{"type":"string","nullable":true},"type":{"type":"string","enum":["DISTRICT","SCHOOL"]},"name":{"type":"string"},"slug":{"type":"string"},"templateId":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PUBLISHED","ARCHIVED"]},"previewSlug":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","districtId","schoolId","type","name","slug","templateId","status","previewSlug","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Archive (soft-delete) a site","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/pages":{"get":{"summary":"List pages for a site","tags":["Websites"],"parameters":[{"schema":{"type":"string","enum":["DRAFT","PUBLISHED","SCHEDULED","ARCHIVED"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"parentId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"parentId":{"type":"string","nullable":true},"title":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["DRAFT","PUBLISHED","SCHEDULED","ARCHIVED"]},"publishedAt":{"type":"string","format":"date-time","nullable":true},"scheduledAt":{"type":"string","format":"date-time","nullable":true},"metaTitle":{"type":"string","nullable":true},"metaDescription":{"type":"string","nullable":true},"position":{"type":"integer"},"inNav":{"type":"boolean"},"isLocked":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","siteId","parentId","title","slug","status","publishedAt","scheduledAt","metaTitle","metaDescription","position","inNav","isLocked","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a page","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9-]+$"},"parentId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["DRAFT","PUBLISHED","SCHEDULED","ARCHIVED"],"default":"DRAFT"},"scheduledAt":{"type":"string","format":"date-time"},"metaTitle":{"type":"string","maxLength":200},"metaDescription":{"type":"string","maxLength":500},"position":{"type":"integer","minimum":0,"default":0},"inNav":{"type":"boolean","default":true}},"required":["title","slug"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"parentId":{"type":"string","nullable":true},"title":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["DRAFT","PUBLISHED","SCHEDULED","ARCHIVED"]},"publishedAt":{"type":"string","format":"date-time","nullable":true},"scheduledAt":{"type":"string","format":"date-time","nullable":true},"metaTitle":{"type":"string","nullable":true},"metaDescription":{"type":"string","nullable":true},"position":{"type":"integer"},"inNav":{"type":"boolean"},"isLocked":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"blocks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"pageId":{"type":"string","format":"uuid"},"type":{"type":"string"},"position":{"type":"integer"},"config":{"type":"object","additionalProperties":{}},"isLocked":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","pageId","type","position","config","isLocked","createdAt","updatedAt"],"additionalProperties":false}}},"required":["id","siteId","parentId","title","slug","status","publishedAt","scheduledAt","metaTitle","metaDescription","position","inNav","isLocked","createdAt","updatedAt","blocks"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/pages/{pageId}":{"get":{"summary":"Get a page with its blocks","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"pageId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"parentId":{"type":"string","nullable":true},"title":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["DRAFT","PUBLISHED","SCHEDULED","ARCHIVED"]},"publishedAt":{"type":"string","format":"date-time","nullable":true},"scheduledAt":{"type":"string","format":"date-time","nullable":true},"metaTitle":{"type":"string","nullable":true},"metaDescription":{"type":"string","nullable":true},"position":{"type":"integer"},"inNav":{"type":"boolean"},"isLocked":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"blocks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"pageId":{"type":"string","format":"uuid"},"type":{"type":"string"},"position":{"type":"integer"},"config":{"type":"object","additionalProperties":{}},"isLocked":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","pageId","type","position","config","isLocked","createdAt","updatedAt"],"additionalProperties":false}}},"required":["id","siteId","parentId","title","slug","status","publishedAt","scheduledAt","metaTitle","metaDescription","position","inNav","isLocked","createdAt","updatedAt","blocks"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a page","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9-]+$"},"parentId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["DRAFT","PUBLISHED","SCHEDULED","ARCHIVED"]},"scheduledAt":{"type":"string","format":"date-time","nullable":true},"metaTitle":{"type":"string","maxLength":200,"nullable":true},"metaDescription":{"type":"string","maxLength":500,"nullable":true},"position":{"type":"integer","minimum":0},"inNav":{"type":"boolean"},"isLocked":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"pageId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"parentId":{"type":"string","nullable":true},"title":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["DRAFT","PUBLISHED","SCHEDULED","ARCHIVED"]},"publishedAt":{"type":"string","format":"date-time","nullable":true},"scheduledAt":{"type":"string","format":"date-time","nullable":true},"metaTitle":{"type":"string","nullable":true},"metaDescription":{"type":"string","nullable":true},"position":{"type":"integer"},"inNav":{"type":"boolean"},"isLocked":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"blocks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"pageId":{"type":"string","format":"uuid"},"type":{"type":"string"},"position":{"type":"integer"},"config":{"type":"object","additionalProperties":{}},"isLocked":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","pageId","type","position","config","isLocked","createdAt","updatedAt"],"additionalProperties":false}}},"required":["id","siteId","parentId","title","slug","status","publishedAt","scheduledAt","metaTitle","metaDescription","position","inNav","isLocked","createdAt","updatedAt","blocks"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a page","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"pageId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/pages/{pageId}/blocks":{"post":{"summary":"Add a block to a page","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","minLength":1,"maxLength":50},"position":{"type":"integer","minimum":0,"default":0},"config":{"type":"object","additionalProperties":{},"default":{}}},"required":["type"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"pageId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"pageId":{"type":"string","format":"uuid"},"type":{"type":"string"},"position":{"type":"integer"},"config":{"type":"object","additionalProperties":{}},"isLocked":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","pageId","type","position","config","isLocked","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/pages/{pageId}/blocks/{blockId}":{"patch":{"summary":"Update a block","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"position":{"type":"integer","minimum":0},"config":{"type":"object","additionalProperties":{}},"isLocked":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"pageId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"blockId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"pageId":{"type":"string","format":"uuid"},"type":{"type":"string"},"position":{"type":"integer"},"config":{"type":"object","additionalProperties":{}},"isLocked":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","pageId","type","position","config","isLocked","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Remove a block","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"pageId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"blockId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/pages/{pageId}/blocks/reorder":{"post":{"summary":"Reorder blocks on a page","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1}},"required":["order"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"pageId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"updated":{"type":"integer"}},"required":["updated"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/branding":{"get":{"summary":"Get branding for a site","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"logoUrl":{"type":"string","nullable":true},"faviconUrl":{"type":"string","nullable":true},"primaryColor":{"type":"string","nullable":true},"secondaryColor":{"type":"string","nullable":true},"accentColor":{"type":"string","nullable":true},"fontPairing":{"type":"string","nullable":true},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","siteId","logoUrl","faviconUrl","primaryColor","secondaryColor","accentColor","fontPairing","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"put":{"summary":"Upsert branding for a site","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"logoUrl":{"type":"string","nullable":true},"faviconUrl":{"type":"string","nullable":true},"primaryColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","nullable":true},"secondaryColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","nullable":true},"accentColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","nullable":true},"fontPairing":{"type":"string","maxLength":100,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"logoUrl":{"type":"string","nullable":true},"faviconUrl":{"type":"string","nullable":true},"primaryColor":{"type":"string","nullable":true},"secondaryColor":{"type":"string","nullable":true},"accentColor":{"type":"string","nullable":true},"fontPairing":{"type":"string","nullable":true},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","siteId","logoUrl","faviconUrl","primaryColor","secondaryColor","accentColor","fontPairing","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/domains":{"get":{"summary":"List domains for a site","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"domain":{"type":"string"},"isPrimary":{"type":"boolean"},"status":{"type":"string","enum":["PENDING","VERIFIED","FAILED"]},"sslStatus":{"type":"string","enum":["PENDING","ACTIVE","EXPIRING","FAILED"]},"verifiedAt":{"type":"string","format":"date-time","nullable":true},"sslIssuedAt":{"type":"string","format":"date-time","nullable":true},"sslExpiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","siteId","domain","isPrimary","status","sslStatus","verifiedAt","sslIssuedAt","sslExpiresAt","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Add a custom domain","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":3,"maxLength":253},"isPrimary":{"type":"boolean","default":false}},"required":["domain"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"domain":{"type":"string"},"isPrimary":{"type":"boolean"},"status":{"type":"string","enum":["PENDING","VERIFIED","FAILED"]},"sslStatus":{"type":"string","enum":["PENDING","ACTIVE","EXPIRING","FAILED"]},"verifiedAt":{"type":"string","format":"date-time","nullable":true},"sslIssuedAt":{"type":"string","format":"date-time","nullable":true},"sslExpiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","siteId","domain","isPrimary","status","sslStatus","verifiedAt","sslIssuedAt","sslExpiresAt","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/domains/{domainId}/verify":{"post":{"summary":"Trigger domain verification","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"domainId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"domain":{"type":"string"},"isPrimary":{"type":"boolean"},"status":{"type":"string","enum":["PENDING","VERIFIED","FAILED"]},"sslStatus":{"type":"string","enum":["PENDING","ACTIVE","EXPIRING","FAILED"]},"verifiedAt":{"type":"string","format":"date-time","nullable":true},"sslIssuedAt":{"type":"string","format":"date-time","nullable":true},"sslExpiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","siteId","domain","isPrimary","status","sslStatus","verifiedAt","sslIssuedAt","sslExpiresAt","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/domains/{domainId}":{"delete":{"summary":"Remove a domain","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"domainId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/redirects":{"get":{"summary":"List redirects for a site","tags":["Websites"],"parameters":[{"schema":{"type":"string","enum":["MANUAL","CRAWL_HIGH","CRAWL_MEDIUM","CRAWL_LOW"]},"in":"query","name":"source","required":false},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"fromPath":{"type":"string"},"toPath":{"type":"string"},"type":{"type":"string","enum":["PERMANENT","TEMPORARY"]},"isWildcard":{"type":"boolean"},"source":{"type":"string","enum":["MANUAL","CRAWL_HIGH","CRAWL_MEDIUM","CRAWL_LOW"]},"confidence":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","siteId","fromPath","toPath","type","isWildcard","source","confidence","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Create a redirect","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fromPath":{"type":"string","minLength":1,"maxLength":500},"toPath":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["PERMANENT","TEMPORARY"],"default":"PERMANENT"},"isWildcard":{"type":"boolean","default":false}},"required":["fromPath","toPath"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"fromPath":{"type":"string"},"toPath":{"type":"string"},"type":{"type":"string","enum":["PERMANENT","TEMPORARY"]},"isWildcard":{"type":"boolean"},"source":{"type":"string","enum":["MANUAL","CRAWL_HIGH","CRAWL_MEDIUM","CRAWL_LOW"]},"confidence":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","siteId","fromPath","toPath","type","isWildcard","source","confidence","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/redirects/{redirectId}":{"patch":{"summary":"Update a redirect","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"toPath":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["PERMANENT","TEMPORARY"]},"isWildcard":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"redirectId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"fromPath":{"type":"string"},"toPath":{"type":"string"},"type":{"type":"string","enum":["PERMANENT","TEMPORARY"]},"isWildcard":{"type":"boolean"},"source":{"type":"string","enum":["MANUAL","CRAWL_HIGH","CRAWL_MEDIUM","CRAWL_LOW"]},"confidence":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","siteId","fromPath","toPath","type","isWildcard","source","confidence","createdAt","updatedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a redirect","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"redirectId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/redirects/bulk-approve":{"post":{"summary":"Bulk approve crawl-suggested redirects","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500}},"required":["ids"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"approved":{"type":"integer"}},"required":["approved"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/media":{"get":{"summary":"List media assets for a site","tags":["Websites"],"parameters":[{"schema":{"type":"string","enum":["IMAGE","DOCUMENT","VIDEO_LINK"]},"in":"query","name":"type","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"filename":{"type":"string"},"url":{"type":"string"},"cdnUrl":{"type":"string","nullable":true},"type":{"type":"string","enum":["IMAGE","DOCUMENT","VIDEO_LINK"]},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer"},"altText":{"type":"string","nullable":true},"width":{"type":"integer","nullable":true},"height":{"type":"integer","nullable":true},"uploadedBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","siteId","filename","url","cdnUrl","type","mimeType","sizeBytes","altText","width","height","uploadedBy","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Register an uploaded media asset","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"url":{"type":"string","format":"uri","maxLength":500},"cdnUrl":{"type":"string","format":"uri","maxLength":500},"type":{"type":"string","enum":["IMAGE","DOCUMENT","VIDEO_LINK"]},"mimeType":{"type":"string","minLength":1,"maxLength":100},"sizeBytes":{"type":"integer","minimum":1},"altText":{"type":"string","maxLength":500},"width":{"type":"integer"},"height":{"type":"integer"},"spacesKey":{"type":"string","minLength":1,"maxLength":500}},"required":["filename","url","type","mimeType","sizeBytes","spacesKey"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"filename":{"type":"string"},"url":{"type":"string"},"cdnUrl":{"type":"string","nullable":true},"type":{"type":"string","enum":["IMAGE","DOCUMENT","VIDEO_LINK"]},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer"},"altText":{"type":"string","nullable":true},"width":{"type":"integer","nullable":true},"height":{"type":"integer","nullable":true},"uploadedBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","siteId","filename","url","cdnUrl","type","mimeType","sizeBytes","altText","width","height","uploadedBy","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/media/{assetId}":{"delete":{"summary":"Soft-delete a media asset","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"assetId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/crawl":{"get":{"summary":"List crawl jobs for a site","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"sourceUrl":{"type":"string"},"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED"]},"startedAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"itemCount":{"type":"integer"},"errorMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","siteId","sourceUrl","status","startedAt","completedAt","itemCount","errorMessage","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Start a site crawl job","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sourceUrl":{"type":"string","format":"uri","maxLength":500}},"required":["sourceUrl"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"sourceUrl":{"type":"string"},"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED"]},"startedAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"itemCount":{"type":"integer"},"errorMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"inventoryJson":{"type":"object","additionalProperties":{},"nullable":true},"gapReportJson":{"type":"object","additionalProperties":{},"nullable":true},"matchesJson":{"type":"object","additionalProperties":{},"nullable":true}},"required":["id","siteId","sourceUrl","status","startedAt","completedAt","itemCount","errorMessage","createdAt","updatedAt","inventoryJson","gapReportJson","matchesJson"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/crawl/{jobId}":{"get":{"summary":"Get crawl job with results","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"jobId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"sourceUrl":{"type":"string"},"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED"]},"startedAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"itemCount":{"type":"integer"},"errorMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"inventoryJson":{"type":"object","additionalProperties":{},"nullable":true},"gapReportJson":{"type":"object","additionalProperties":{},"nullable":true},"matchesJson":{"type":"object","additionalProperties":{},"nullable":true}},"required":["id","siteId","sourceUrl","status","startedAt","completedAt","itemCount","errorMessage","createdAt","updatedAt","inventoryJson","gapReportJson","matchesJson"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/permissions":{"get":{"summary":"List editor permissions for a site","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"personId":{"type":"string"},"role":{"type":"string","enum":["ADMIN","EDITOR","VIEWER"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","siteId","personId","role","createdAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"post":{"summary":"Add an editor to a site","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["ADMIN","EDITOR","VIEWER"]}},"required":["personId","role"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"personId":{"type":"string"},"role":{"type":"string","enum":["ADMIN","EDITOR","VIEWER"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","siteId","personId","role","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/sites/{siteId}/permissions/{permId}":{"patch":{"summary":"Update editor role","tags":["Websites"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["ADMIN","EDITOR","VIEWER"]}},"required":["role"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"permId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"siteId":{"type":"string","format":"uuid"},"personId":{"type":"string"},"role":{"type":"string","enum":["ADMIN","EDITOR","VIEWER"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","siteId","personId","role","createdAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}},"delete":{"summary":"Remove an editor from a site","tags":["Websites"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"permId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/websites/preview/{previewSlug}":{"get":{"summary":"Get site layout (public)","tags":["Websites – Preview"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":120},"in":"path","name":"previewSlug","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"site":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["DISTRICT","SCHOOL"]},"status":{"type":"string","enum":["DRAFT","PUBLISHED","ARCHIVED"]}},"required":["id","name","type","status"],"additionalProperties":false},"branding":{"type":"object","properties":{"logoUrl":{"type":"string","nullable":true},"faviconUrl":{"type":"string","nullable":true},"primaryColor":{"type":"string","nullable":true},"secondaryColor":{"type":"string","nullable":true},"accentColor":{"type":"string","nullable":true},"fontPairing":{"type":"string","nullable":true}},"required":["logoUrl","faviconUrl","primaryColor","secondaryColor","accentColor","fontPairing"],"additionalProperties":false,"nullable":true},"navPages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"parentId":{"type":"string","nullable":true},"position":{"type":"integer"}},"required":["id","title","slug","parentId","position"],"additionalProperties":false}}},"required":["site","branding","navPages"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/websites/preview/{previewSlug}/page":{"get":{"summary":"Get a page with blocks (public)","tags":["Websites – Preview"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"slug","required":false},{"schema":{"type":"string","minLength":1,"maxLength":120},"in":"path","name":"previewSlug","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"metaTitle":{"type":"string","nullable":true},"metaDescription":{"type":"string","nullable":true},"blocks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"position":{"type":"integer"},"config":{"type":"object","additionalProperties":{}}},"required":["id","type","position","config"],"additionalProperties":false}}},"required":["id","title","slug","metaTitle","metaDescription","blocks"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/websites/preview/{previewSlug}/live-data":{"get":{"summary":"Get live district data for website blocks (public)","tags":["Websites – Preview"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":120},"in":"path","name":"previewSlug","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"district":{"type":"object","properties":{"name":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string","nullable":true},"city":{"type":"string"},"state":{"type":"string"},"zipCode":{"type":"string"},"studentCount":{"type":"integer"},"staffCount":{"type":"integer"}},"required":["name","addressLine1","addressLine2","city","state","zipCode","studentCount","staffCount"],"additionalProperties":false,"nullable":true},"events":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"title":{"type":"string"},"dayType":{"type":"string"}},"required":["date","title","dayType"],"additionalProperties":false}},"news":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"sentAt":{"type":"string"}},"required":["id","subject","body","sentAt"],"additionalProperties":false}},"staff":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"photoUrl":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}},"required":["id","firstName","lastName","photoUrl","email"],"additionalProperties":false}}},"required":["district","events","news","staff"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/integrations/oneroster/outbound/export":{"get":{"summary":"Generate and download a OneRoster 1.2 CSV ZIP export","tags":["Integrations · OneRoster"],"description":"Generates a complete OneRoster 1.2 bulk export for the district and returns it as a ZIP file. Requires the district to be on Professional or Enterprise plan.","parameters":[{"schema":{"type":"string","format":"date"},"in":"query","name":"asOf","required":false}],"responses":{"200":{"description":"application/zip binary","content":{"application/json":{"schema":{"description":"application/zip binary"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/integrations/oneroster/outbound/status":{"get":{"summary":"Last OneRoster export metadata","tags":["Integrations · OneRoster"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"lastExportAt":{"type":"string","nullable":true},"lastExportAsOf":{"type":"string","nullable":true},"lastExportRowCounts":{"type":"object","additionalProperties":{"type":"number"},"nullable":true},"pushEndpointConfigured":{"type":"boolean"},"lastPushAt":{"type":"string","nullable":true},"lastPushStatus":{"type":"string","nullable":true}},"required":["lastExportAt","lastExportAsOf","lastExportRowCounts","pushEndpointConfigured","lastPushAt","lastPushStatus"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/integrations/oneroster/outbound/sync":{"post":{"summary":"Push OneRoster export to configured endpoint","tags":["Integrations · OneRoster"],"description":"Generates a fresh OneRoster export and pushes it to the configured push endpoint. Configure the endpoint URL + bearer token in district settings.oneRoster.endpointUrl / .bearerToken.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string","format":"date"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"},"statusCode":{"type":"integer"},"rowCounts":{"type":"object","additionalProperties":{"type":"number"}},"pushedAt":{"type":"string"}},"required":["ok","statusCode","rowCounts","pushedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/integrations/oneroster/outbound/config":{"patch":{"summary":"Save the OneRoster outbound push endpoint config","tags":["Integrations · OneRoster"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"endpointUrl":{"type":"string","format":"uri"},"bearerToken":{"type":"string","minLength":1}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/integrations/m365/config":{"get":{"summary":"Get M365 integration config for the district","tags":["Integrations · Microsoft 365"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tenantId":{"type":"string"},"clientId":{"type":"string"},"syncEnabled":{"type":"boolean"},"lastSyncAt":{"type":"string","nullable":true},"configured":{"type":"boolean"}},"required":["tenantId","clientId","syncEnabled","lastSyncAt","configured"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"patch":{"summary":"Update M365 tenantId, clientId, or sync toggle","tags":["Integrations · Microsoft 365"],"description":"Update the M365 configuration. Client secret is NOT stored here — set it as an environment variable: ${DISTRICT_ID}__M365_CLIENT_SECRET.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenantId":{"type":"string","minLength":1,"maxLength":200},"clientId":{"type":"string","minLength":1,"maxLength":200},"syncEnabled":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["ok","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/integrations/m365/sync-users":{"post":{"summary":"Sync all active students and staff to M365","tags":["Integrations · Microsoft 365"],"description":"Provisions or updates all active STUDENT and STAFF persons in Azure AD. Respects the configured tenantId/clientId and reads M365_CLIENT_SECRET from env.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"failed":{"type":"integer"},"errors":{"type":"array","items":{"type":"string"}},"completedAt":{"type":"string"}},"required":["created","updated","failed","errors","completedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/integrations/m365/sync-teams":{"post":{"summary":"Sync section roster as Teams class groups","tags":["Integrations · Microsoft 365"],"description":"Creates or updates Microsoft Teams Education class groups for each active section. Each section becomes a Teams class with the lead teacher as owner.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"failed":{"type":"integer"},"errors":{"type":"array","items":{"type":"string"}},"completedAt":{"type":"string"}},"required":["created","updated","failed","errors","completedAt"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/integrations/m365/sync-status":{"get":{"summary":"Last M365 sync results","tags":["Integrations · Microsoft 365"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"lastSyncAt":{"type":"string","nullable":true},"lastSyncStats":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"failed":{"type":"integer"},"errors":{"type":"array","items":{"type":"string"}},"completedAt":{"type":"string"}},"required":["created","updated","failed","errors","completedAt"],"additionalProperties":false,"nullable":true}},"required":["lastSyncAt","lastSyncStats"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/dashboard/summary":{"get":{"summary":"Super Admin: aggregate platform metrics","tags":["Platform"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"districts":{"type":"object","properties":{"total":{"type":"integer"},"active":{"type":"integer"},"trial":{"type":"integer"},"churned":{"type":"integer"},"byStatus":{"type":"object","additionalProperties":{"type":"integer"}}},"required":["total","active","trial","churned","byStatus"],"additionalProperties":false},"billing":{"type":"object","properties":{"mrr":{"type":"number"},"arr":{"type":"number"},"trialEndingSoon":{"type":"integer"}},"required":["mrr","arr","trialEndingSoon"],"additionalProperties":false},"usage":{"type":"object","properties":{"totalStudents":{"type":"integer"},"totalStaff":{"type":"integer"},"aiCallsLast24h":{"type":"integer"},"aiSpendLast24h":{"type":"number"},"eventsLastHour":{"type":"integer"}},"required":["totalStudents","totalStaff","aiCallsLast24h","aiSpendLast24h","eventsLastHour"],"additionalProperties":false},"people":{"type":"object","properties":{"totalUsers":{"type":"integer"},"totalGuardians":{"type":"integer"}},"required":["totalUsers","totalGuardians"],"additionalProperties":false}},"required":["districts","billing","usage","people"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts":{"get":{"summary":"Super Admin: list every district","tags":["Platform"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":2,"maxLength":2},"in":"query","name":"state","required":false},{"schema":{"type":"string","maxLength":30},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cdsCode":{"type":"string"},"name":{"type":"string"},"shortName":{"type":"string","nullable":true},"state":{"type":"string"},"city":{"type":"string"},"type":{"type":"string"},"subscriptionPlan":{"type":"string"},"subscriptionStatus":{"type":"string"},"trialEndsAt":{"type":"string","format":"date-time","nullable":true},"mrr":{"type":"number"},"arr":{"type":"number"},"studentCount":{"type":"integer"},"staffCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","cdsCode","name","shortName","state","city","type","subscriptionPlan","subscriptionStatus","trialEndsAt","mrr","arr","studentCount","staffCount","createdAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}},"post":{"summary":"Super Admin: provision a new district","tags":["Platform"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cdsCode":{"type":"string","minLength":2,"maxLength":12},"name":{"type":"string","minLength":2,"maxLength":200},"shortName":{"type":"string","maxLength":50,"nullable":true},"type":{"type":"string","enum":["PUBLIC","CHARTER","PRIVATE","DIOCESE","CONSORTIUM"]},"addressLine1":{"type":"string","minLength":2,"maxLength":200},"addressLine2":{"type":"string","maxLength":200,"nullable":true},"city":{"type":"string","minLength":1,"maxLength":100},"state":{"type":"string","minLength":2,"maxLength":2},"zipCode":{"type":"string","minLength":5,"maxLength":10},"county":{"type":"string","minLength":1,"maxLength":100},"timezone":{"type":"string","default":"America/New_York"},"subscriptionPlan":{"type":"string","default":"trial"},"subscriptionStatus":{"type":"string","enum":["trial","active","past_due","suspended","churned"],"default":"trial"},"trialDays":{"type":"integer","minimum":0,"maximum":365,"default":30},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["cdsCode","name","type","addressLine1","city","state","zipCode","county","reason"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/audit":{"get":{"summary":"Recent platform audit entries","tags":["Platform"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":50},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"actorId":{"type":"string","nullable":true},"action":{"type":"string"},"targetDistrictId":{"type":"string","format":"uuid","nullable":true},"reason":{"type":"string"},"ipAddress":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":{},"nullable":true},"occurredAt":{"type":"string","format":"date-time"}},"required":["id","actorId","action","targetDistrictId","reason","ipAddress","metadata","occurredAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/platform/v1/feature-flags":{"get":{"summary":"Feature flags with per-district override counts","tags":["Platform"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"description":{"type":"string"},"defaultOn":{"type":"boolean"},"overrideCount":{"type":"integer"}},"required":["id","key","description","defaultOn","overrideCount"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}},"post":{"summary":"Super Admin: create a feature flag","tags":["Platform"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":3,"maxLength":100,"pattern":"^[a-z][a-z0-9._-]*$"},"description":{"type":"string","minLength":3,"maxLength":500},"defaultOn":{"type":"boolean","default":false},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["key","description","reason"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"description":{"type":"string"},"defaultOn":{"type":"boolean"},"overrideCount":{"type":"integer"}},"required":["id","key","description","defaultOn","overrideCount"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{id}":{"get":{"summary":"Super Admin: district detail","tags":["Platform"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cdsCode":{"type":"string"},"name":{"type":"string"},"shortName":{"type":"string","nullable":true},"type":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string","nullable":true},"city":{"type":"string"},"state":{"type":"string"},"zipCode":{"type":"string"},"county":{"type":"string"},"timezone":{"type":"string"},"subscriptionPlan":{"type":"string"},"subscriptionStatus":{"type":"string"},"trialEndsAt":{"type":"string","format":"date-time","nullable":true},"activatedAt":{"type":"string","format":"date-time","nullable":true},"paidThroughDate":{"type":"string","format":"date-time","nullable":true},"contractStartDate":{"type":"string","format":"date-time","nullable":true},"contractEndDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"mrr":{"type":"number"},"arr":{"type":"number"},"studentCount":{"type":"integer"},"staffCount":{"type":"integer"},"userCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","cdsCode","name","shortName","type","addressLine1","addressLine2","city","state","zipCode","county","timezone","subscriptionPlan","subscriptionStatus","trialEndsAt","activatedAt","paidThroughDate","contractStartDate","contractEndDate","autoRenew","mrr","arr","studentCount","staffCount","userCount","createdAt","updatedAt"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Super Admin: edit district","tags":["Platform"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":200},"shortName":{"type":"string","maxLength":50,"nullable":true},"type":{"type":"string","enum":["PUBLIC","CHARTER","PRIVATE","DIOCESE","CONSORTIUM"]},"addressLine1":{"type":"string","minLength":2,"maxLength":200},"addressLine2":{"type":"string","maxLength":200,"nullable":true},"city":{"type":"string","minLength":1,"maxLength":100},"state":{"type":"string","minLength":2,"maxLength":2},"zipCode":{"type":"string","minLength":5,"maxLength":10},"county":{"type":"string","minLength":1,"maxLength":100},"timezone":{"type":"string"},"subscriptionPlan":{"type":"string"},"autoRenew":{"type":"boolean"},"contractStartDate":{"type":"string","format":"date-time","nullable":true},"contractEndDate":{"type":"string","format":"date-time","nullable":true},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{id}/status":{"post":{"summary":"Super Admin: activate / suspend / churn a district","tags":["Platform"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["trial","active","past_due","suspended","churned"]},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["status","reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"status":{"type":"string"}},"required":["ok","status"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{id}/users":{"get":{"summary":"Super Admin: list users of a district","tags":["Platform"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","maxLength":30},"in":"query","name":"status","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"name":{"type":"string","nullable":true},"status":{"type":"string"},"mfaEnabled":{"type":"boolean"},"lastLoginAt":{"type":"string","format":"date-time","nullable":true},"lastLoginIp":{"type":"string","nullable":true},"failedLoginCount":{"type":"integer"},"personType":{"type":"string","nullable":true},"roles":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","email","name","status","mfaEnabled","lastLoginAt","lastLoginIp","failedLoginCount","personType","roles","createdAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{id}/users/{userId}/status":{"post":{"summary":"Super Admin: activate / suspend / disable a district user","tags":["Platform"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","suspended","disabled"]},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["status","reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"userId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"status":{"type":"string"}},"required":["ok","status"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{id}/users/{userId}/roles":{"patch":{"summary":"Super Admin: replace role set for a district user","tags":["Platform"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"roles":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":0,"maxItems":20},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["roles","reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"userId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"roles":{"type":"array","items":{"type":"string"}}},"required":["ok","roles"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"unknown":{"type":"array","items":{"type":"string"}}},"required":["error","unknown"],"additionalProperties":false}}}}}}},"/api/platform/v1/operators":{"get":{"summary":"Super Admin: list YRC operators","tags":["Platform"],"parameters":[{"schema":{"type":"string","maxLength":30},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"displayName":{"type":"string"},"role":{"type":"string"},"mfaEnabled":{"type":"boolean"},"status":{"type":"string"},"lastLoginAt":{"type":"string","format":"date-time","nullable":true},"auditCount":{"type":"integer"},"isSystem":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","email","displayName","role","mfaEnabled","status","lastLoginAt","auditCount","isSystem","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}},"post":{"summary":"Super Admin: invite a new YRC operator","tags":["Platform"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":200},"displayName":{"type":"string","minLength":2,"maxLength":200},"role":{"type":"string","enum":["platform_owner","platform_admin","platform_support","platform_engineer","platform_billing","platform_readonly"]},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["email","displayName","role","reason"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"temporaryPassword":{"type":"string"}},"required":["id","temporaryPassword"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/operators/{id}":{"patch":{"summary":"Super Admin: update YRC operator","tags":["Platform"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","minLength":2,"maxLength":200},"role":{"type":"string","enum":["platform_owner","platform_admin","platform_support","platform_engineer","platform_billing","platform_readonly"]},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/operators/{id}/status":{"post":{"summary":"Super Admin: activate / suspend / disable YRC operator","tags":["Platform"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","suspended","disabled"]},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["status","reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"status":{"type":"string"}},"required":["ok","status"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/operators/{id}/reset-password":{"post":{"summary":"Super Admin: generate a new temporary password","tags":["Platform"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"temporaryPassword":{"type":"string"}},"required":["temporaryPassword"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{id}/feature-flags":{"get":{"summary":"Super Admin: all flags with this district's overrides","tags":["Platform"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"description":{"type":"string"},"defaultOn":{"type":"boolean"},"overrideCount":{"type":"integer"},"districtOverride":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"enabled":{"type":"boolean"},"reason":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","enabled","reason","expiresAt"],"additionalProperties":false,"nullable":true}},"required":["id","key","description","defaultOn","overrideCount","districtOverride"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/feature-flags/{key}":{"patch":{"summary":"Super Admin: update feature flag default / description","tags":["Platform"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"defaultOn":{"type":"boolean"},"description":{"type":"string","minLength":3,"maxLength":500},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","maxLength":100},"in":"path","name":"key","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"key":{"type":"string"},"defaultOn":{"type":"boolean"},"description":{"type":"string"}},"required":["key","defaultOn","description"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{id}/feature-flags/{key}/override":{"post":{"summary":"Super Admin: set a district-level feature flag override","tags":["Platform"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"reason":{"type":"string","minLength":3,"maxLength":500},"expiresAt":{"type":"string","format":"date-time","nullable":true}},"required":["enabled","reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","maxLength":100},"in":"path","name":"key","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"districtId":{"type":"string","format":"uuid"},"flagKey":{"type":"string"},"enabled":{"type":"boolean"},"reason":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","districtId","flagKey","enabled","reason","expiresAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"summary":"Super Admin: remove a district-level feature flag override","tags":["Platform"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","maxLength":100},"in":"path","name":"key","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/integrations/districts/{districtId}/connectors":{"get":{"summary":"List available connectors and their configuration status for a district","tags":["Platform · Integrations"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"vendor":{"type":"string"},"version":{"type":"string"},"supportsBackfill":{"type":"boolean"},"supportsRealtime":{"type":"boolean"},"isConfigured":{"type":"boolean"},"lastSyncedAt":{"type":"string","format":"date-time","nullable":true},"lastSyncStatus":{"type":"string","nullable":true}},"required":["id","displayName","vendor","version","supportsBackfill","supportsRealtime","isConfigured","lastSyncedAt","lastSyncStatus"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/integrations/districts/{districtId}/connectors/{id}/config":{"put":{"summary":"Upsert a connector configuration for a district","tags":["Platform · Integrations"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","minLength":1,"maxLength":200},"config":{"type":"object","additionalProperties":{},"default":{}},"secretRefs":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"isActive":{"type":"boolean","default":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"connectorId":{"type":"string"},"displayName":{"type":"string"},"isActive":{"type":"boolean"},"config":{"type":"object","additionalProperties":{}},"secretRefs":{"type":"object","additionalProperties":{"type":"string"}}},"required":["id","connectorId","displayName","isActive","config","secretRefs"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/integrations/districts/{districtId}/sync-runs":{"get":{"summary":"History of connector sync runs for a district","tags":["Platform · Integrations"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string"},"in":"query","name":"connectorId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"connectorId":{"type":"string"},"mode":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"recordsRead":{"type":"integer"},"eventsEmitted":{"type":"integer"},"failures":{"type":"integer"},"errorMessage":{"type":"string","nullable":true},"stats":{"type":"object","additionalProperties":{},"nullable":true}},"required":["id","connectorId","mode","status","startedAt","completedAt","recordsRead","eventsEmitted","failures","errorMessage","stats"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"totalApprox":{"type":"integer","minimum":0}},"required":["cursor","nextCursor","hasMore"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","pagination","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/integrations/districts/{districtId}/genesis/import":{"post":{"summary":"Import a Genesis CSV export into a district","tags":["Platform · Integrations"],"description":"Paste CSV bodies directly. Default `dryRun: true` — run once to preview counts, then set false to apply.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","default":true},"studentsCsv":{"type":"string","minLength":10},"guardiansCsv":{"type":"string"},"enrollmentsCsv":{"type":"string","minLength":10}},"required":["studentsCsv","enrollmentsCsv"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"type":"string","format":"uuid"},"dryRun":{"type":"boolean"},"stats":{"type":"object","properties":{"personsCreated":{"type":"integer"},"personsUpdated":{"type":"integer"},"guardianshipsLinked":{"type":"integer"},"enrollmentsCreated":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"recordType":{"type":"string"},"localId":{"type":"string"},"message":{"type":"string"}},"required":["recordType","message"],"additionalProperties":false}}},"required":["personsCreated","personsUpdated","guardianshipsLinked","enrollmentsCreated","errors"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}}},"required":["runId","dryRun","stats","warnings"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/integrations/districts/{districtId}/powerschool/import":{"post":{"summary":"Import a PowerSchool CSV export into a district","tags":["Platform · Integrations"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","default":true},"studentsCsv":{"type":"string","minLength":10},"guardiansCsv":{"type":"string"},"enrollmentsCsv":{"type":"string","minLength":10}},"required":["studentsCsv","enrollmentsCsv"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"type":"string","format":"uuid"},"dryRun":{"type":"boolean"},"stats":{"type":"object","properties":{"personsCreated":{"type":"integer"},"personsUpdated":{"type":"integer"},"guardianshipsLinked":{"type":"integer"},"enrollmentsCreated":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"recordType":{"type":"string"},"localId":{"type":"string"},"message":{"type":"string"}},"required":["recordType","message"],"additionalProperties":false}}},"required":["personsCreated","personsUpdated","guardianshipsLinked","enrollmentsCreated","errors"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}}},"required":["runId","dryRun","stats","warnings"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/integrations/districts/{districtId}/oneroster/import":{"post":{"summary":"Import a OneRoster 1.2 CSV set into a district","tags":["Platform · Integrations"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","default":true},"usersCsv":{"type":"string","minLength":10},"enrollmentsCsv":{"type":"string","minLength":10}},"required":["usersCsv","enrollmentsCsv"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"type":"string","format":"uuid"},"dryRun":{"type":"boolean"},"stats":{"type":"object","properties":{"personsCreated":{"type":"integer"},"personsUpdated":{"type":"integer"},"guardianshipsLinked":{"type":"integer"},"enrollmentsCreated":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"recordType":{"type":"string"},"localId":{"type":"string"},"message":{"type":"string"}},"required":["recordType","message"],"additionalProperties":false}}},"required":["personsCreated","personsUpdated","guardianshipsLinked","enrollmentsCreated","errors"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}}},"required":["runId","dryRun","stats","warnings"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/integrations/districts/{districtId}/lti/launch":{"post":{"summary":"Canvas LTI 1.3 launch endpoint (scaffold)","tags":["Platform · Integrations"],"description":"Accepts the LTI 1.3 `id_token` POST from Canvas, validates the JWT against the configured platform keys, and redirects the user into Forge with a session. M11 ships the endpoint shape; full JWT validation + user provisioning lands when a district configures Canvas.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id_token":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["id_token","state"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ltiAccepted":{"type":"boolean","enum":[true]},"redirectTo":{"type":"string"}},"required":["ltiAccepted","redirectTo"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/integrations/lti/schoology/config":{"get":{"summary":"Schoology LTI 1.3 registration metadata","tags":["Platform · Integrations"],"description":"Returns the Schoology LTI 1.3 registration payload. Requires `integration.admin` permission. Use this to populate Schoology LTI tool registration manually or via the register endpoint.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"districtId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"platform":{"type":"string"},"platformUrl":{"type":"string"},"keysetUrl":{"type":"string"},"authEndpoint":{"type":"string"},"tokenEndpoint":{"type":"string"},"registrationPayload":{"type":"object","additionalProperties":{}}},"required":["platform","platformUrl","keysetUrl","authEndpoint","tokenEndpoint","registrationPayload"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/integrations/districts/{districtId}/lti/schoology/register":{"post":{"summary":"Register Forge as Schoology LTI 1.3 tool","tags":["Platform · Integrations"],"description":"Calls Schoology API to register the Forge SIS LTI tool for a district.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"apiKey":{"type":"string","minLength":1},"apiSecret":{"type":"string","minLength":1}},"required":["apiKey","apiSecret"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"toolId":{"type":"string"},"clientId":{"type":"string"},"applicationId":{"type":"string"},"message":{"type":"string"}},"required":["success","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/integrations/lti/blackboard/config":{"get":{"summary":"Blackboard LTI 1.3 registration metadata","tags":["Platform · Integrations"],"description":"Returns the Blackboard LTI 1.3 registration payload. Requires `integration.admin` permission. Use this to populate Blackboard LTI tool registration manually or via the register endpoint.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"districtId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"platform":{"type":"string"},"platformUrl":{"type":"string"},"keysetUrl":{"type":"string"},"authEndpoint":{"type":"string"},"tokenEndpoint":{"type":"string"},"registrationPayload":{"type":"object","additionalProperties":{}}},"required":["platform","platformUrl","keysetUrl","authEndpoint","tokenEndpoint","registrationPayload"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/integrations/districts/{districtId}/lti/blackboard/register":{"post":{"summary":"Register Forge as Blackboard LTI 1.3 tool","tags":["Platform · Integrations"],"description":"Calls Blackboard API to register the Forge SIS LTI tool for a district.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"apiKey":{"type":"string","minLength":1},"apiSecret":{"type":"string","minLength":1}},"required":["apiKey","apiSecret"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"toolId":{"type":"string"},"clientId":{"type":"string"},"applicationId":{"type":"string"},"message":{"type":"string"}},"required":["success","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"traceId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{id}/billing":{"get":{"summary":"Get subscription info for a district","tags":["Platform · Billing"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plan":{"type":"string","enum":["starter","professional","enterprise"]},"status":{"type":"string","enum":["active","trialing","past_due","cancelled"]},"stripeCustomerId":{"type":"string"},"stripeSubscriptionId":{"type":"string"},"currentPeriodEnd":{"type":"string"},"trialEndsAt":{"type":"string"},"aiUsageCentsTotal":{"type":"number"}},"required":["plan","status"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{id}/billing/create-customer":{"post":{"summary":"Create a Stripe customer for a district","tags":["Platform · Billing"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","minLength":1,"maxLength":200},"reason":{"type":"string","minLength":3,"maxLength":500,"default":"Customer created via signup."}},"required":["email","name"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"stripeCustomerId":{"type":"string"}},"required":["stripeCustomerId"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{id}/billing/subscribe":{"post":{"summary":"Create a Stripe subscription for a district","tags":["Platform · Billing"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"priceId":{"type":"string","minLength":1},"plan":{"type":"string","enum":["starter","professional","enterprise"]},"reason":{"type":"string","minLength":3,"maxLength":500,"default":"Subscription created."}},"required":["priceId","plan"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionId":{"type":"string"},"clientSecret":{"type":"string"}},"required":["subscriptionId"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{id}/billing/cancel":{"post":{"summary":"Cancel the Stripe subscription for a district","tags":["Platform · Billing"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{id}/invoices":{"get":{"summary":"List invoices for a district","tags":["Platform · Billing"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"stripeInvoiceId":{"type":"string"},"stripeInvoiceUrl":{"type":"string"},"periodStart":{"type":"string"},"periodEnd":{"type":"string"},"totalCents":{"type":"integer"},"status":{"type":"string"},"pdfUrl":{"type":"string"},"aiUsageCredits":{"type":"integer"},"createdAt":{"type":"string"}},"required":["id","totalCents","status","createdAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/billing/prospects":{"get":{"summary":"List Stripe checkouts pending or completed district provisioning","tags":["Platform — Billing"],"parameters":[{"schema":{"type":"boolean"},"in":"query","name":"provisioned","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"auditId":{"type":"string","format":"uuid"},"customerEmail":{"type":"string","nullable":true},"planCode":{"type":"string","nullable":true},"amountTotalCents":{"type":"integer"},"currency":{"type":"string"},"stripeSessionId":{"type":"string"},"stripeCustomerId":{"type":"string","nullable":true},"stripeSubscriptionId":{"type":"string","nullable":true},"receivedAt":{"type":"string","format":"date-time"},"provisioned":{"type":"boolean"},"provisionedDistrictId":{"type":"string","format":"uuid","nullable":true}},"required":["auditId","customerEmail","planCode","amountTotalCents","currency","stripeSessionId","stripeCustomerId","stripeSubscriptionId","receivedAt","provisioned","provisionedDistrictId"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/billing/prospects/{auditId}/provision":{"post":{"summary":"Provision a District + initial district_admin user from a prospect","tags":["Platform — Billing"],"description":"Creates the District row using the supplied details, an initial User with the prospect email as a district_admin, and binds the existing Stripe customer/subscription. Idempotent — if the prospect was already provisioned, returns the existing districtId.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cdsCode":{"type":"string","minLength":1,"maxLength":12},"name":{"type":"string","minLength":1,"maxLength":200},"shortName":{"type":"string","maxLength":50},"type":{"type":"string","enum":["PUBLIC","CHARTER","PRIVATE","DIOCESE","CONSORTIUM"]},"addressLine1":{"type":"string","minLength":1,"maxLength":200},"city":{"type":"string","minLength":1,"maxLength":100},"state":{"type":"string","minLength":2,"maxLength":2},"zipCode":{"type":"string","minLength":5,"maxLength":10},"county":{"type":"string","minLength":1,"maxLength":100},"timezone":{"type":"string","minLength":1,"maxLength":50,"default":"America/New_York"},"adminPassword":{"type":"string","minLength":12,"maxLength":72}},"required":["cdsCode","name","type","addressLine1","city","state","zipCode","county"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"auditId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"districtId":{"type":"string","format":"uuid"},"adminUserId":{"type":"string","format":"uuid"},"adminEmail":{"type":"string"},"welcomeEmailSent":{"type":"boolean"}},"required":["districtId","adminUserId","adminEmail"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/logs/processes":{"get":{"summary":"List PM2 processes with status + uptime","tags":["Platform — Logs"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"processes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string"},"restarts":{"type":"integer"},"uptimeMs":{"type":"integer","nullable":true},"memoryBytes":{"type":"integer","nullable":true},"pmId":{"type":"integer","nullable":true}},"required":["name","status","restarts","uptimeMs","memoryBytes","pmId"],"additionalProperties":false}}},"required":["processes"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/platform/v1/logs/tail":{"get":{"summary":"Tail the last N lines of a process log","tags":["Platform — Logs"],"parameters":[{"schema":{"type":"string","enum":["forge-api","forge-web","forge-admin","forge-worker","forge-monitor","forge-nightly-projections","forge-nightly-truancy","forge-nightly-asset-book-values","forge-nightly-dashboard-snapshots","forge-nightly-backup-upload"]},"in":"query","name":"process","required":true},{"schema":{"type":"string","enum":["out","err"],"default":"out"},"in":"query","name":"stream","required":false},{"schema":{"type":"integer","minimum":10,"maximum":2000,"default":200},"in":"query","name":"lines","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"process":{"type":"string"},"stream":{"type":"string","enum":["out","err"]},"lines":{"type":"integer"},"log":{"type":"string"}},"required":["process","stream","lines","log"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/platform/v1/queues":{"get":{"summary":"List BullMQ queue depths","tags":["Platform — Queues"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"waiting":{"type":"integer"},"active":{"type":"integer"},"delayed":{"type":"integer"},"completed":{"type":"integer"},"failed":{"type":"integer"},"paused":{"type":"integer"}},"required":["name","waiting","active","delayed","completed","failed","paused"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/queues/{name}/failed":{"get":{"summary":"List recent failed jobs in a queue","tags":["Platform — Queues"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"name","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"attemptsMade":{"type":"integer"},"failedReason":{"type":"string","nullable":true},"data":{},"timestamp":{"type":"integer","nullable":true},"finishedOn":{"type":"integer","nullable":true}},"required":["id","name","attemptsMade","failedReason","timestamp","finishedOn"],"additionalProperties":false}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"timestamp":{"type":"string"},"correlationId":{"type":"string"}},"required":["requestId","timestamp"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{id}/ai-usage":{"get":{"summary":"Per-district AI usage report for billing passthrough","tags":["Platform · Billing"],"description":"Returns AI token counts and USD cost for a district in the given period. If `from` and `to` are omitted, defaults to the rolling 30-day window. The `invoiceLineItem` field is pre-formatted for inclusion on a platform invoice.","parameters":[{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"districtId":{"type":"string","format":"uuid"},"periodStart":{"type":"string"},"periodEnd":{"type":"string"},"totalCents":{"type":"integer"},"tokenCount":{"type":"integer"},"invoiceLineItem":{"type":"object","properties":{"description":{"type":"string"},"totalCents":{"type":"integer"},"tokenCount":{"type":"integer"}},"required":["description","totalCents","tokenCount"],"additionalProperties":false,"nullable":true}},"required":["districtId","periodStart","periodEnd","totalCents","tokenCount","invoiceLineItem"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/reconciler/run":{"post":{"summary":"Trigger projection reconciliation (all districts or one)","tags":["Platform","Reconciler"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"districtId":{"type":"string","format":"uuid"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"districtId":{"type":"string"},"ranAt":{"type":"string","format":"date-time"},"durationMs":{"type":"integer"},"findings":{"type":"array","items":{"type":"object","properties":{"checkName":{"type":"string"},"districtId":{"type":"string"},"expected":{"anyOf":[{"type":"number"},{"type":"string"}]},"actual":{"anyOf":[{"type":"number"},{"type":"string"}]},"driftPct":{"type":"number"},"severity":{"type":"string","enum":["info","warn","critical"]}},"required":["checkName","districtId","expected","actual","driftPct","severity"],"additionalProperties":false}}},"required":["districtId","ranAt","durationMs","findings"],"additionalProperties":false}},"totalMs":{"type":"integer"}},"required":["results","totalMs"],"additionalProperties":false}}}}}}},"/api/platform/v1/reconciler/status":{"get":{"summary":"Last reconciler run summary per district","tags":["Platform","Reconciler"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"criticalOnly","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"districtId":{"type":"string","format":"uuid"},"name":{"type":"string"},"lastRun":{"type":"object","properties":{"ranAt":{"type":"string"},"durationMs":{"type":"number"},"criticalFindings":{"type":"array","items":{"type":"object","properties":{"checkName":{"type":"string"},"districtId":{"type":"string"},"expected":{"anyOf":[{"type":"number"},{"type":"string"}]},"actual":{"anyOf":[{"type":"number"},{"type":"string"}]},"driftPct":{"type":"number"},"severity":{"type":"string","enum":["info","warn","critical"]}},"required":["checkName","districtId","expected","actual","driftPct","severity"],"additionalProperties":false}}},"required":["ranAt","durationMs","criticalFindings"],"additionalProperties":false,"nullable":true}},"required":["districtId","name","lastRun"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{districtId}/api-keys":{"get":{"summary":"Super Admin: list API keys for a district","tags":["Platform"],"description":"Returns all non-revoked API keys for the district. The key hash is never returned.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string"},"keyPrefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"ipAllowlist":{"type":"array","items":{"type":"string"},"nullable":true},"rateLimit":{"type":"object","properties":{"requestsPerMinute":{"type":"integer"}},"required":["requestsPerMinute"],"additionalProperties":false,"nullable":true},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","type","keyPrefix","scopes","ipAllowlist","rateLimit","lastUsedAt","expiresAt","createdAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Super Admin: create an API key for a district","tags":["Platform"],"description":"Generates a cryptographically random key. The plaintext key is returned ONCE and cannot be retrieved again.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"type":{"type":"string","enum":["public","secret","admin","partner"]},"scopes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1},"expiresAt":{"type":"string","format":"date-time"},"ipAllowlist":{"type":"array","items":{"type":"string","minLength":1,"maxLength":45}},"rateLimit":{"type":"object","properties":{"requestsPerMinute":{"type":"integer","minimum":1,"maximum":100000}},"required":["requestsPerMinute"],"additionalProperties":false}},"required":["name","type","scopes"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string"},"keyPrefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"plaintextKey":{"type":"string"}},"required":["id","name","type","keyPrefix","scopes","expiresAt","createdAt","plaintextKey"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/districts/{districtId}/api-keys/{keyId}":{"delete":{"summary":"Super Admin: revoke an API key","tags":["Platform"],"description":"Soft-deletes the key by setting revokedAt to now. The key stops working immediately.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"districtId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"keyId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/api/platform/v1/webhooks/stripe/billing":{"post":{"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://api.forgesis.com/v1","description":"Production"},{"url":"https://api.staging.forgesis.com/v1","description":"Staging"},{"url":"http://localhost:4000/v1","description":"Local dev"}],"security":[{"bearerAuth":[]},{"apiKey":[]}],"tags":[{"name":"Meta","description":"Health, readiness, version."},{"name":"Students","description":"Student records and derived data."},{"name":"Guardians","description":"Parent/guardian records."},{"name":"Staff","description":"Staff and faculty records."},{"name":"Sections","description":"Course sections and rosters."},{"name":"Attendance","description":"Daily and period attendance."},{"name":"Gradebook","description":"Assignments, scores, and posted grades."},{"name":"Scheduling","description":"Courses, terms, and master schedule."},{"name":"Health","description":"Nurse visits, medications, immunizations, screenings."},{"name":"Discipline","description":"Incidents, actions, HIB investigations."},{"name":"Communications","description":"Messages, broadcasts, templates."},{"name":"Registration","description":"Online enrollment submissions."},{"name":"Reports","description":"Standard, custom, and NL reports."},{"name":"Compliance","description":"State reporting and compliance checks."},{"name":"Webhooks","description":"Outbound event subscriptions."},{"name":"Admin","description":"District administrator tools."}]}