{ "openapi": "3.1.0", "info": { "title": "GoGuardian Extension REST API", "version": "4.0.7422.1", "description": "Complete REST/HTTP surface of the GoGuardian student-monitoring Chrome extension, reconstructed from its minified webpack bundles (v4.0.7422.1). Every fact below is verified against the reconstructed source tree: request/response field names, content types, schedules, retry policies and evidence citations come from the wire-level extraction pass (module numbers refer to files under source/background/src/ and source/background/raw-modules/).\nAUTH MODEL — the generic HTTP client (module 149, base https://extapi.goguardian.com) sets on every request: \"Authorization\" = the raw compRand token (NO \"Bearer\" prefix; the token is issued by POST /api/v1/ext/register and stored in localStorage.compRand), and \"ExtensionVersion\" = the running extension version. When present and parseable, a \"Device-Id\" header (localStorage.enterpriseDirectoryDeviceId) is also sent. A few hand-rolled clients (beacon predictors, lesson-plan, Twilio) send lowercase \"authorization\"/\"extensionversion\" variants.\nHOST OVERRIDE QUIRK — the server can repoint any path to a different host via an apiMap (delivered with privacy settings): ajax() checks apiMap[fullPathString] before falling back to the default base, keyed by the complete path string, not a prefix.\nENCODING — module-149 POST/PUT calls that pass a plain data object are jQuery form-encoded (application/x-www-form-urlencoded) by default; only calls that explicitly set contentType send JSON. Binary pipelines gzip an Avro record (entity batch, statsd) or a protobuf message (roll-call, apps-exts) and post it as application/binary or application/octet-stream.\nHONEST CAVEAT — response schemas list only the fields the client code actually reads; servers return more. Entries marked \"response not read\" are fire-and-forget. Uncertainties from the extraction pass are called out inline." }, "servers": [ { "url": "https://extapi.goguardian.com", "description": "Default base for the module-149 HTTP client. All paths on other hosts carry their own path-level servers." } ], "security": [ { "CompRand": [], "ExtensionVersion": [] } ], "tags": [ { "name": "Registration & Identity", "description": "Bootstrap registration, account/user state, name/email identity." }, { "name": "Settings & Policy", "description": "Privacy, admin policy, experiments, notifications, model sync." }, { "name": "Surveillance", "description": "Entity batch (Avro/gzip), roll-call heartbeat, screenshots." }, { "name": "Telemetry", "description": "StatsD metrics and log shipping (Avro / JSON to countvoncount)." }, { "name": "Smart Alerts (X3)", "description": "Self-harm content prediction and report pipeline (x3-*)." }, { "name": "Beacon (crisis response)", "description": "Fullpage/search predictors and beacon reports shown to students." }, { "name": "Classroom & Calls", "description": "Chat messages, lesson plans, video-call participants." }, { "name": "Taskiness & Video", "description": "Off-task scoring and YouTube video metadata." }, { "name": "Pusher Auth", "description": "Channel authorization for the realtime Pusher connection." }, { "name": "Utilities", "description": "Public IP, clock sync, native-agent liveness, diagnostics." }, { "name": "Block Pages", "description": "Navigations to blocked.goguardian.com with signed context params." }, { "name": "S3 Upload", "description": "Server-signed multipart uploads to an S3 bucket." } ], "paths": { "/api/v1/ext/register": { "post": { "tags": [ "Registration & Identity" ], "operationId": "register", "summary": "Exchange license-extension IDs for org identity and compRand token", "description": "First call of the bootstrap. The extension lists installed extensions (chrome.management), filters for those named exactly \"Chromium License\" or \"GoGuardian License\", and POSTs their extension IDs as orgRands (also stored to localStorage.orgRand). The server maps them to the org and returns the register payload merged verbatim into state.register. Retried 1 s base delay, 8 attempts. Failure path: \"No License, please install license extension.\" -> Register subsystem wipes localStorage.uuid and reloads the extension after 60 s.", "x-evidence": "raw-modules/1403.js:23-51, raw-modules/1337.js:19-40, src/1519-register.js:93-101", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } } }, "responses": { "200": { "description": "Register payload merged into state.register (reducer 1337).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" } } } } } } }, "/api/v1/ext/version": { "put": { "tags": [ "Registration & Identity" ], "operationId": "reportVersion", "summary": "Report a running version newer than the server's record", "description": "Sent only when the running version compares greater than user.extVer from GET /api/v1/ext/user. Failure is logged and non-fatal.", "x-evidence": "src/1521-user.js:149-154", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/VersionRequest" } } } }, "responses": { "200": { "description": "Response not read." } } } }, "/api/v1/ext/bypass": { "get": { "tags": [ "Settings & Policy" ], "operationId": "validateBypassPassword", "summary": "Validate a block-page bypass password", "description": "Called by the background Bypass subsystem when the student submits the block-page bypass form (admin bundle UI opens a runtime port; the background performs the call). On success the server returns a bypass window (time in minutes; bypassEnd = now + 60*time) and the tab is navigated to the target URL. CORRECTION of the earlier markdown doc (source/docs/WEB-AND-REALTIME-APIs.md): the wire call is GET on the extapi default base, not POST on snat — raw/1606.js is authoritative.", "x-evidence": "raw-modules/1606.js:30-47, raw-modules/689.js:63-65", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Target URL to unblock (\"www.\" prefix stripped by the UI).", "schema": { "type": "string" } }, { "name": "password", "in": "query", "required": true, "description": "Bypass password (UI port message field is \"pw\"; wire field is \"password\").", "schema": { "type": "string" } }, { "name": "profiles", "in": "query", "required": true, "description": "The profiles array (window.profiles) from registration.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Bypass grant. Failure answers \"fail\" via the UI port.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BypassResponse" } } } } } } }, "/api/v1/ext/nameandemail": { "post": { "tags": [ "Registration & Identity" ], "operationId": "createAccount", "summary": "Create/identify the student account from a scraped identity", "description": "Native fetch (not module 149) with form-encoded body built by jQuery.param. Headers: content-type application/x-www-form-urlencoded, authorization (compRand), extensionversion (lowercase). Retried 1 s base, 7 attempts. The identity \"url\" field is one of \"chrome.identity\", \"windows.nativehost\", \"chrome.identity.windows.nativehost\".", "x-evidence": "raw-modules/986.js:63-85, raw-modules/986.js:192-223", "security": [ { "CompRand": [], "ExtensionVersion": [] } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/NameAndEmailRequest" } } } }, "responses": { "200": { "description": "Response fields read: accountId, profiles (kept on window.profiles).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountResponse" } } } } } } }, "/api/v1/ext/updatename": { "put": { "tags": [ "Registration & Identity" ], "operationId": "updateName", "summary": "Update the student's scraped display name", "x-evidence": "raw-modules/986.js:195-199", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Response not read." } } } }, "/api/v1/ext/googleprofile": { "put": { "tags": [ "Registration & Identity" ], "operationId": "updateGoogleProfile", "summary": "Update the student's Google profile ID", "x-evidence": "raw-modules/986.js:202-223", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "googleProfileId": { "type": "string" } }, "required": [ "googleProfileId" ] } } } }, "responses": { "200": { "description": "Response not read." } } } }, "/assets/scripts/ext/submitCoordsGuard.php": { "post": { "tags": [ "Surveillance" ], "operationId": "submitGeolocation", "summary": "Hourly student geolocation upload (legacy PHP path)", "description": "navigator.geolocation.getCurrentPosition with timeout 10 s and enableHighAccuracy; error callback is a no-op. Fired every GEOLOCATION_UPDATE_INTERVAL_MS = 3600000 (1 h), once immediately on enable; gated on admin.monitorEnabled AND a license set containing \"admin\". Fire-and-forget — response never read.", "x-evidence": "raw-modules/1556.js:16-51, src/336-intervals.js:21", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/GeolocationRequest" } } } }, "responses": { "200": { "description": "Response not read (fire-and-forget)." } } } }, "/api/v1/ext/user": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Registration & Identity" ], "operationId": "getUser", "summary": "Fetch user/account state", "description": "Merged verbatim into state.user. Drives the OrgRand mismatch check (if server orgRand is not among the locally installed Chromium/GoGuardian License extension IDs, the extension wipes localStorage and reloads after 60 s) and the email mismatch check (emailOnFile vs chrome.identity email triggers the same wipe).", "x-evidence": "raw-modules/1404.js:10-17, raw-modules/1338.js:28-47, src/1521-user.js:110-178", "responses": { "200": { "description": "User payload merged into state.user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } } } } }, "/api/v2/ext/privacy": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Settings & Policy" ], "operationId": "getPrivacySettings", "summary": "Fetch privacy settings (delivers the apiMap and feature gates)", "description": "Polled every 1000000 ms (task \"updatePrivacySettings\"); response cached at chrome.storage.local key \"local_data\". The privacy response installs apiMap (full-path -> host overrides for the module-149 client) on every refresh. HTTP 403 wipes localStorage and reloads the extension.", "x-evidence": "raw-modules/689.js:101-107, src/1523-privacy.js:64-111", "parameters": [ { "name": "version", "in": "query", "required": false, "description": "Current privacy version (client-passed cache-buster).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Privacy settings bundle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyResponse" } } } } } } }, "/api/v1/ext/policy": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Settings & Policy" ], "operationId": "getAdminPolicy", "summary": "Fetch admin blocking policy (site filters)", "description": "Polled every 900000 ms (15 min, GETPOLICY_INTERVAL_MS).", "x-evidence": "raw-modules/852.js:99-105, src/336-intervals.js:22", "parameters": [ { "name": "version", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "required": false, "description": "moment.tz.guess() result.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Admin policy (site filters, categories, schedules). Shape not exhaustively reconstructed — schema is loose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" } } } } } } }, "/api/v1/ext/experiments": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Settings & Policy" ], "operationId": "getExperiments", "summary": "Fetch experiment assignment lists", "description": "Validated response; retried 1 s base, 10 attempts.", "x-evidence": "raw-modules/1756.js:10-22", "responses": { "200": { "description": "Experiment assignment/exposure lists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentsResponse" } } } } } } }, "/api/v1/ext/notifications": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Settings & Policy" ], "operationId": "getNotifications", "summary": "Poll for student-visible notifications", "description": "Polled every 900000 ms (GET_NOTIFICATIONS_INTERVAL_MS).", "x-evidence": "raw-modules/1772.js:10-14, src/336-intervals.js:33", "responses": { "200": { "description": "Notification list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsResponse" } } } } } } }, "/api/v1/ext/chat-messages": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Classroom & Calls" ], "operationId": "getChatMessages", "summary": "Fetch classroom chat history for a session", "description": "Client parseInts each message's studentId from the response.", "x-evidence": "raw-modules/1709.js:20-33", "parameters": [ { "name": "sessionId", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Chat history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMessagesResponse" } } } } } } }, "/api/v1/ext/diagnose": { "servers": [ { "url": "https://snat.goguardian.com" } ], "post": { "tags": [ "Utilities" ], "operationId": "submitDiagnostics", "summary": "Dump full extension state on checkup navigation", "description": "Fired when a tab navigates to https://checkup.goguardian.com. Body is a JSON.stringify of the full redux state plus Pusher channel info.", "x-evidence": "raw-modules/1530.js:34, raw-modules/1530.js:82-88", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DiagnoseRequest" } } } }, "responses": { "200": { "description": "Response not read." } } } }, "/api/v1/ext/deviceId": { "servers": [ { "url": "https://snat.goguardian.com" } ], "post": { "tags": [ "Registration & Identity" ], "operationId": "registerDeviceId", "summary": "Register the enterprise-directory device ID", "description": "dataType \"text\"; retried 1 s base, 3 attempts. Sends deviceId, or a reason (\"Not Provisioned\") when the enterprise API did not supply one.", "x-evidence": "raw-modules/1607.js:77-92", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DeviceIdRequest" } } } }, "responses": { "200": { "description": "Response not read (dataType text)." } } } }, "/api/v1/ext/app-exts": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Surveillance" ], "operationId": "getAppExtsSnapshot", "summary": "Fetch the server's snapshot of installed extensions/apps", "description": "Used to diff against the local chrome.management list before syncing.", "x-evidence": "raw-modules/1569.js:92-98", "responses": { "200": { "description": "Installed id list; shape not reconstructed (raw 1569 diff logic)." } } } }, "/api/v1/ext/smart-filtering/settings": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Settings & Policy" ], "operationId": "getSmartFilteringSettings", "summary": "Fetch smart-filtering configuration (hosted domains, proxy matchers)", "description": "Response cached; used to configure proxy/direct-IP blocking.", "x-evidence": "raw-modules/1641.js:92-98", "responses": { "200": { "description": "Smart-filtering settings; shape not reconstructed." } } } }, "/api/v1/ext/smart-filtering/models/explicit/{version}/model.json": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Settings & Policy" ], "operationId": "getExplicitImageModel", "summary": "Fetch the TF.js explicit-image model for a version", "x-evidence": "raw-modules/1625.js:180", "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "TF.js model JSON. Consumed by the explicit-image-filter pipeline.", "content": { "application/json": {} } } } } }, "/api/v1/ext/smart-filtering/models/explicit/{version}/metadata.json": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Settings & Policy" ], "operationId": "getExplicitImageModelMetadata", "summary": "Fetch metadata for the explicit-image model version", "x-evidence": "raw-modules/1625.js:243", "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Model metadata JSON.", "content": { "application/json": {} } } } } }, "/api/v1/ext/smart-filtering/models/proxies/version/current": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Settings & Policy" ], "operationId": "getProxiesModelCurrentVersion", "summary": "Current keyword-model version for proxy detection", "x-evidence": "raw-modules/1644.js:9", "responses": { "200": { "description": "Version descriptor consumed by module 1644." } } } }, "/api/v1/ext/smart-filtering/models/proxies/{version}/model.json": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Settings & Policy" ], "operationId": "getProxiesModel", "summary": "Fetch proxy keyword model for a version", "description": "Synced every 900000 ms.", "x-evidence": "raw-modules/1644.js:26", "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Keyword model JSON." } } } }, "/api/v1/ext/smart-filtering/models/threats/version/current": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Settings & Policy" ], "operationId": "getThreatsModelCurrentVersion", "summary": "Current keyword-model version for threats detection", "x-evidence": "raw-modules/1646.js:9", "responses": { "200": { "description": "Version descriptor consumed by module 1646." } } } }, "/api/v1/ext/smart-filtering/models/threats/{version}/model.json": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Settings & Policy" ], "operationId": "getThreatsModel", "summary": "Fetch threats keyword model for a version", "x-evidence": "raw-modules/1646.js:27", "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Keyword model JSON." } } } }, "/api/v2/ext/lesson-plan/{id}": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Classroom & Calls" ], "operationId": "getLessonPlan", "summary": "Fetch a lesson plan scene definition", "description": "Hand-rolled client with lowercase authorization/extensionversion headers; backoff initial 1 s, max 10 s with jitter; retried only on network errors and 5xx.", "x-evidence": "raw-modules/1047.js:83-130", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lesson-plan scene JSON (restricted sites etc.); shape not reconstructed.", "content": { "application/json": {} } } } } }, "/api/v2/ext/ggt-calls/{callId}/participants": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Classroom & Calls" ], "operationId": "getCallParticipants", "summary": "Fetch participants of a teacher-student video call", "description": "contentType application/json; retried 500 ms base, 5 attempts.", "x-evidence": "raw-modules/1051.js:196-218", "parameters": [ { "name": "callId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Call participant list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantsResponse" } } } } } } }, "/api/v2/ext/ggt-calls/{callId}/participant/{id}": { "servers": [ { "url": "https://snat.goguardian.com" } ], "get": { "tags": [ "Classroom & Calls" ], "operationId": "getCallParticipant", "summary": "Fetch a single call participant", "x-evidence": "raw-modules/1051.js:196-218", "parameters": [ { "name": "callId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "One participant record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Participant" } } } } } } }, "/v1/entitybatchpreauth": { "servers": [ { "url": "https://quiddity.goguardian.com" } ], "post": { "tags": [ "Surveillance" ], "operationId": "submitEntityBatch", "summary": "Main surveillance pipeline — gzipped Avro entity batches", "description": "Headers set in beforeSend: Authorization (compRand || \"Unknown\"), ExtensionVersion (|| \"Unknown\"), Content-type application/binary, Content-encoding gzip. Body is a Blob([binary], type application/binary) where binary = pako.gzip(1-byte schema version + Avro-serialized EntityBatchPreAuth). Schema version = 13 (shipped as avro/resources/EntityBatchPreAuth.version). Flushed by TaskManager task \"entities_flush\" every 60000 ms (1000 ms fast interval during mlPipeline rate-increase); immediate flush on a new search entity when mlPipeline is enabled; final flush when monitoring disables. Gated on admin.monitorEnabled (or the dataCollectionAllEntities feature). On POST failure the pending keys are NOT marked flushed (only statsd admin.entity_submission.error) so they retry next flush; entities that fail Avro trial serialization are dropped and the rest ships. Internal pipeline name \"kinesis\".", "x-evidence": "src/1741-flush-entities-thunk.js:83-139, src/1740-entities-flush.js:44-110, src/1736-entity-manager-v3.js, source/background/…/EntityBatchPreAuth.avsc", "requestBody": { "required": true, "content": { "application/binary": { "schema": { "type": "string", "format": "binary" }, "description": "gzip(0x0D || avro(EntityBatchPreAuth)). The decoded record shape is documented as the informational components EntityBatchPreAuthRecord / EntityPreAuth." } } }, "responses": { "200": { "description": "Response not read; success releases the batch keys." } } } }, "/v1/roll-call": { "servers": [ { "url": "https://waluigi.goguardian.com" } ], "post": { "tags": [ "Surveillance" ], "operationId": "rollCall", "summary": "Protobuf attendance heartbeat", "description": "Body: protobuf waluigi.RollCallRequest.create({...}).encode().finish() — field 1 extensionVersion (string, tag 0x0A), field 2 ip (uint64, tag 0x10; ipv4 packed as 256*(256*(256*a+b)+c)+d). Content-Type application/octet-stream. TaskManager task \"rollCall\" every 300000 ms (5 min) plus immediate fire on monitor enable. Gated on priv.settings.features.eventTransportSettings.roll_call existing and !rollCall.disabled AND admin.monitorEnabled. Retried 1 s base, 3 attempts; failure statsd \"luigi_roll_call.error\". Client checks only response.ok; RPC return type waluigi.SuccessResponse.", "x-evidence": "src/1541-attendance.js:48-88, raw-modules/989.js:64-101", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "description": "protobuf RollCallRequest { extensionVersion: string (f1), ip: uint64 (f2) }" } } }, "responses": { "200": { "description": "waluigi.SuccessResponse; only response.ok checked." } } } }, "/v1/create-apps-exts": { "servers": [ { "url": "https://waluigi.goguardian.com" } ], "post": { "tags": [ "Surveillance" ], "operationId": "createAppsExts", "summary": "Sync newly installed apps/extensions (protobuf)", "description": "protobuf CreateAppsExtsRequest: f1 extensionVersion (string), f2 ip (uint64), f3 repeated AppsExtsPayload { extID f1, extName f2, extJSON f3, isApp f4, description f5, homepageURL f6, iconURL f7 }. Content-Type application/octet-stream, processData false. Diffed against GET /api/v1/ext/app-exts before sending.", "x-evidence": "raw-modules/1569.js:150-162, raw-modules/989.js:270-298", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "description": "protobuf CreateAppsExtsRequest" } } }, "responses": { "200": { "description": "Response not read." } } } }, "/v1/delete-apps-exts": { "servers": [ { "url": "https://waluigi.goguardian.com" } ], "post": { "tags": [ "Surveillance" ], "operationId": "deleteAppsExts", "summary": "Sync removed apps/extensions (protobuf)", "description": "protobuf DeleteAppsExtsRequest: f1 extensionVersion (string), f2 ip (uint64), f3 repeated ids (string). Sent at most every SEND_EXTENSIONS_RATE_MS = 3600000 ms (1 h).", "x-evidence": "raw-modules/1569.js:169-186, raw-modules/989.js:634-660, src/336-intervals.js:24", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "description": "protobuf DeleteAppsExtsRequest" } } }, "responses": { "200": { "description": "Response not read." } } } }, "/v1/snapshots": { "servers": [ { "url": "https://screenshots.goguardian.com" } ], "post": { "tags": [ "Surveillance" ], "operationId": "uploadSnapshot", "summary": "Upload a live teacher-view screenshot (raw JPEG)", "description": "opts { processData: false, contentType: \"image/jpeg\" }; body is the raw JPEG bytes after canvas resize to maxDimension (800 legacy; liveStateVersion >= 4: 500, or 1600 during resolution-increase) at quality 80. The response must echo the client md5 as hash or the client throws \"hash mismatch!\"; url is the teacher-facing link. md5 dedupe: a NodeCache (stdTTL 30 s) keyed by md5 skips re-upload; expirations are debounced (500 ms) into a \"snapshotsExpired\" event.", "x-evidence": "src/1716-image-handler.js:82-228, src/1715-live-state.js:199-201", "requestBody": { "required": true, "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" }, "description": "Raw JPEG bytes (md5 computed over these)." } } }, "responses": { "200": { "description": "Snapshot descriptor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotResponse" } } } } } } }, "/v1/snapshots/{hash}": { "servers": [ { "url": "https://screenshots.goguardian.com" } ], "put": { "tags": [ "Surveillance" ], "operationId": "keepSnapshotAlive", "summary": "Snapshot TTL keepalive", "description": "TaskManager task \"image-handler-update-ttl\" every 20000 ms (20 s); skipped when no snapshot is cached. Body is the literal string \"{}\".", "x-evidence": "src/1716-image-handler.js:96-100, src/1716-image-handler.js:252-258", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "Response not read." } } } }, "/v1/activity-snapshots": { "servers": [ { "url": "https://screenshots.goguardian.com" } ], "post": { "tags": [ "Surveillance" ], "operationId": "uploadActivitySnapshot", "summary": "Upload a permanent activity screenshot (data URL)", "description": "JPEG data-URL captured at quality 75 (snapHeavy(null, 75)); cached with TTL 960 s and shipped when its screenshotTime falls inside the entity flush window or its seqId is in a server-requested backfill (seqIdsToCollect).", "x-evidence": "src/411-snapper.js:69-81, src/1736-entity-manager-v3.js:186-243", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivitySnapshotRequest" } } } }, "responses": { "200": { "description": "Response not read." } } } }, "/v1/statsd": { "servers": [ { "url": "https://countvoncount.goguardian.com" } ], "post": { "tags": [ "Telemetry" ], "operationId": "submitStatsdBatch", "summary": "StatsD metrics batch (1-byte version + Avro, application/binary)", "description": "Headers: Authorization (compRand || \"Unknown\"), ExtensionVersion, Content-type application/binary. Blob([versionByte ++ avro.toBuffer(record)]) where versionByte = StatsDBatch.version = 1 (avro/resources/StatsDBatch.version). Flushed by task \"statsd_flush\" every 30000 ms; buffer capped at 100 metrics (keeps newest); retried 1 s base, 3 attempts, failure re-queues with statsd \"statsd.submit_error\". Metric names are prefixed \"chromium_m.\".", "x-evidence": "src/182-statsd-client.js:42-115", "requestBody": { "required": true, "content": { "application/binary": { "schema": { "type": "string", "format": "binary" }, "description": "0x01 || avro(StatsDBatchRecord)" } } }, "responses": { "200": { "description": "Response not read." } } } }, "/v2/logs": { "servers": [ { "url": "https://countvoncount.goguardian.com" } ], "post": { "tags": [ "Telemetry" ], "operationId": "submitLogs", "summary": "Log shipping (JSON batch; server-side Avro schema)", "description": "contentType application/json, processData false; body JSON.stringify( { logs, submissionTime }). Flushed by task \"logs_flush\" every 30000 ms, 100 records per batch; retried 1 s base, 3 attempts, failure re-queues with statsd \"logs.submit_error\". Client records carry severity / log / stack_trace (module-678 logger); every record is pre-tagged with account_id, extension_version, os, org_id, sub_account_id. Server deserializes with avro LogsBatch.Log { logMessage, level INFO|WARN|ERROR, timestampMs, errorName, errorMessage, errorStack } — the exact client->server key mapping is not visible in the extension (uncertainty N3 of the extraction).", "x-evidence": "src/24-log-client.js:44-180", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogsRequest" } } } }, "responses": { "200": { "description": "Response not read." } } } }, "/v2/predictions": { "servers": [ { "url": "https://x3-predictor.goguardian.com" } ], "post": { "tags": [ "Smart Alerts (X3)" ], "operationId": "predictX3V2", "summary": "Keyword-list self-harm prediction (gzipped base64)", "description": "contentType: false, timeout 10000 ms, headers Authorization + X-GG-X3EXTVER. Body: btoa(pako.gzip(JSON.stringify({words}))) — a base64 string of gzipped JSON with a single array field \"words\". Retried 3 attempts at 500 * 2^n ms. Response data.prediction.{category, probability}.", "x-evidence": "raw-modules/1610.js:26-46", "requestBody": { "required": true, "content": { "text/plain": { "schema": { "type": "string" }, "description": "btoa(gzip(JSON({words:[...]})))" } } }, "responses": { "200": { "description": "Prediction result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prediction": { "$ref": "#/components/schemas/X3Prediction" } } } } } } } } }, "/v3/predictions": { "servers": [ { "url": "https://x3-predictor.goguardian.com" } ], "post": { "tags": [ "Smart Alerts (X3)" ], "operationId": "predictX3V3", "summary": "Full-text self-harm prediction (gzip binary)", "description": "Headers Authorization + ExtensionVersion; body pako.gzip(JSON.stringify({fullText})). This endpoint is used ONLY when the X3 policy's disabledCategories includes \"self-harm\" (which disables it elsewhere). Response data.prediction.{category, probability, threshold{low,medium,high}}.", "x-evidence": "raw-modules/1009.js:56-77", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "description": "gzip(JSON({fullText}))" } } }, "responses": { "200": { "description": "Prediction with thresholds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prediction": { "type": "object", "properties": { "category": { "type": "string" }, "probability": { "type": "number" }, "threshold": { "type": "object", "properties": { "low": { "type": "number" }, "medium": { "type": "number" }, "high": { "type": "number" } } } } } } } } } } } } }, "/proxy/v1/predictions": { "servers": [ { "url": "https://x3-predictor.goguardian.com" } ], "post": { "tags": [ "Smart Alerts (X3)" ], "operationId": "predictX3Proxy", "summary": "Full-text prediction via CORS proxy (base64 deflate)", "description": "contentType: false. Body: btoa(pako.deflate(JSON.stringify({ fullText (capped at 30000 chars, truncated at the last space), requestID (ISO date with ms truncated to 19 chars, \"T\" replaced by \"-\", then \"-\" + url.slice(0,500)) }))). Response data.{probability, threshold{very_high, high, medium}}.", "x-evidence": "raw-modules/1009.js:32-92, raw-modules/1643.js:144-167", "requestBody": { "required": true, "content": { "text/plain": { "schema": { "type": "string" }, "description": "btoa(deflate(JSON({fullText, requestID})))" } } }, "responses": { "200": { "description": "Proxy prediction result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "probability": { "type": "number" }, "threshold": { "type": "object", "properties": { "very_high": { "type": "number" }, "high": { "type": "number" }, "medium": { "type": "number" } } } } } } } } } } }, "/v1/reports": { "servers": [ { "url": "https://x3-reporter.goguardian.com" } ], "post": { "tags": [ "Smart Alerts (X3)" ], "operationId": "createX3Report", "summary": "Submit a self-harm alert report", "description": "contentType \"application/json; charset=utf-8\", timeout 7000 ms, headers Authorization + X-GG-X3EXTVER. Retried 3 attempts at 500 * 2^n ms. Response {reportId, contentDescriptor, screenshotDescriptor, imageDescriptor}.", "x-evidence": "raw-modules/697.js:31-47", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X3ReportRequest" } } } }, "responses": { "200": { "description": "Report created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X3ReportResponse" } } } } } } }, "/v1/beacon/reports": { "servers": [ { "url": "https://x3-reporter.goguardian.com" } ], "post": { "tags": [ "Beacon (crisis response)" ], "operationId": "createBeaconReport", "summary": "Submit a Beacon crisis report", "description": "Hand-rolled fetch: lowercase headers authorization / x-gg-x3extver. JSON {url, timestamp, prediction, closedMessage: false, didMessage, seqId, model: \"FULLPAGE_PREDICTOR\" | \"TV_SEARCH_PREDICTOR\"}. Retried 1 s base, 3 attempts. Response {reportId, contentDescriptor, screenshotDescriptor}.", "x-evidence": "src/1652-beacon-reporter.js:538-562", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconReportRequest" } } } }, "responses": { "200": { "description": "Beacon report created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconReportResponse" } } } } } } }, "/v1/beacon/reports/{reportId}": { "servers": [ { "url": "https://x3-reporter.goguardian.com" } ], "put": { "tags": [ "Beacon (crisis response)" ], "operationId": "closeBeaconReport", "summary": "Mark a Beacon report's crisis message closed", "description": "Lowercase headers. Body {closedMessage: true}. Retried 1 s base, 3 attempts. Fired after the crisis help modal is dismissed.", "x-evidence": "src/1652-beacon-reporter.js:436-459", "parameters": [ { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "closedMessage" ], "properties": { "closedMessage": { "type": "boolean", "enum": [ true ] } } } } } }, "responses": { "200": { "description": "Response not read." } } } }, "/v1/policy": { "servers": [ { "url": "https://x3-policy-maker.goguardian.com" } ], "get": { "tags": [ "Smart Alerts (X3)" ], "operationId": "getX3Policy", "summary": "Smart Alerts trigger policy", "description": "timeout 7000 ms, retried 1 s base, 10 attempts. Response cached under key \"triggers\". Response fields read: triggers.messages[] / triggers.blocks[] (items: triggerId, name, message, threshold, category, ou, triggerSources, blockTarget), blockedCategories (mapped to disabledCategories), disabledImageFilteringSiteCategories.", "x-evidence": "raw-modules/1621.js:100-153", "responses": { "200": { "description": "X3 trigger policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X3Policy" } } } } } } }, "/v1/beacon/policy": { "servers": [ { "url": "https://x3-policy-maker.goguardian.com" } ], "get": { "operationId": "getBeaconPolicy", "tags": [ "Beacon (crisis response)" ], "summary": "Beacon deployment policy (15-minute refresh)", "description": "Refreshed every 15 min, cached under key \"beacon\". HTTP 400 with error code 9 means \"not deployed\" and silently disables Beacon.", "x-evidence": "raw-modules/1651.js:92-98", "responses": { "200": { "description": "Beacon policy (may be an empty deployment marker).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconPolicy" } } } }, "400": { "description": "Error code 9 = Beacon not deployed for this org." } } } }, "/v1/beacon/fullpage": { "servers": [ { "url": "https://beacon-fullpage-predictor.goguardian.com" } ], "post": { "tags": [ "Beacon (crisis response)" ], "operationId": "predictBeaconFullpage", "summary": "Full-page crisis scan", "description": "Hand-rolled fetch with lowercase headers. Body is the content object produced by the Beacon miner with its url field set. Retried 1 s base, 3 attempts. Response data.prediction.{phase, probability}.", "x-evidence": "src/1652-beacon-reporter.js:203, src/1652-beacon-reporter.js:460-484", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Miner content object with url set." } } } }, "responses": { "200": { "description": "Fullpage prediction.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prediction": { "$ref": "#/components/schemas/BeaconPrediction" } } } } } } } } }, "/threats-and-violence/predict": { "servers": [ { "url": "https://ml-endpoint.goguardian.com" } ], "post": { "tags": [ "Beacon (crisis response)" ], "operationId": "predictThreatsAndViolence", "summary": "Threats-and-violence search-term prediction", "description": "JSON {searchterm}. Response data.{phase, probability}. Used by the TV_SEARCH_PREDICTOR Beacon model on search terms.", "x-evidence": "src/1652-beacon-reporter.js:660-684", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "searchterm" ], "properties": { "searchterm": { "type": "string" } } } } } }, "responses": { "200": { "description": "TV prediction.", "content": { "application/json": { "schema": { "type": "object", "properties": { "phase": { "type": "string" }, "probability": { "type": "number" } } } } } } } } }, "/device-notifications/v1/get-notifications": { "servers": [ { "url": "https://x3-policy-maker.goguardian.com" } ], "get": { "tags": [ "Smart Alerts (X3)" ], "operationId": "getDeviceNotifications", "summary": "Poll admin device notifications", "description": "Retried 1 s base, 10 attempts. Response read for notifications destined to this device/session (processed through the student-notifications module).", "x-evidence": "raw-modules/1043.js", "responses": { "200": { "description": "Pending notifications.", "content": { "application/json": { "schema": { "type": "object", "description": "Exact shape not reconstructed." } } } } } } }, "/device-notifications/v1/ack": { "servers": [ { "url": "https://x3-policy-maker.goguardian.com" } ], "post": { "tags": [ "Smart Alerts (X3)" ], "operationId": "ackDeviceNotifications", "summary": "Acknowledge device notifications", "description": "JSON {ack_ids:[...]} of notification ids being acknowledged. Retried 1 s base, 10 attempts.", "x-evidence": "raw-modules/1043.js", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ack_ids" ], "properties": { "ack_ids": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Response not read." } } } }, "/api/v1/ext/fullurl/categories": { "servers": [ { "url": "https://panther.goguardian.com" } ], "get": { "tags": [ "Utilities" ], "operationId": "categorizeUrl", "summary": "Server-side URL categorization", "description": "Query parameter url (the full URL to categorize). Retried 1 s base, 3 attempts. Response read as {categories:[{cats:[...]}]} (first categories entry used).", "x-evidence": "raw-modules/859.js:12-30", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Category lookup result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "cats": { "type": "array", "items": { "type": "string" } } } } } } } } } } } } }, "/taskiness_score": { "servers": [ { "url": "https://taskiness-preprocessor.goguardian.com" } ], "post": { "tags": [ "Taskiness & Video" ], "operationId": "scoreTaskiness", "summary": "On-task scoring for a subject's full text", "description": "URL carries a subject query parameter (e.g. ?subject=). Body is the plain-text fullText (content type text/plain). Response is a map subject -> {score} plus a timestamp.", "x-evidence": "raw-modules/1725.js:267-299", "parameters": [ { "name": "subject", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "text/plain": { "schema": { "type": "string" }, "description": "The full text to score." } } }, "responses": { "200": { "description": "Taskiness scores keyed by subject.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "score": { "type": "number" } } }, "description": "Plus a timestamp field alongside the subject keys." } } } } } } }, "/v1/video": { "servers": [ { "url": "https://play-button.goguardian.com" } ], "get": { "tags": [ "Taskiness & Video" ], "operationId": "getVideoMetadata", "summary": "YouTube video metadata lookup", "description": "Query parameter videoID. Response data.video is read (fields consumed: ID, ageRestricted, channelID, categoryID, plus others remapped into VideoMetadata).", "x-evidence": "raw-modules/1602.js:15-38", "parameters": [ { "name": "videoID", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Video metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "video": { "type": "object", "description": "Fields actually consumed: ID, ageRestricted, channelID, categoryID (remapped into VideoMetadata).", "properties": { "ID": { "type": "string" }, "ageRestricted": { "type": "boolean" }, "channelID": { "type": "string" }, "categoryID": { "type": "string" } } } } } } } } } } }, "/ip": { "servers": [ { "url": "https://ip.goguardian.com" } ], "get": { "tags": [ "Utilities" ], "operationId": "getPublicIp", "summary": "Public IPv4 discovery (no auth)", "description": "security: [] — no compRand/ExtensionVersion headers are sent. Response is a dotted quad string. Refresh task every 60000 ms; timeout 5 s, retried 1 s base, 5 attempts; fallback \"0.0.0.0\".", "x-evidence": "raw-modules/692.js:41-77", "security": [], "responses": { "200": { "description": "Dotted-quad IPv4 string.", "content": { "text/plain": { "schema": { "type": "string", "example": "203.0.113.7" } } } } } } }, "/api/v1/auth/ext": { "servers": [ { "url": "https://sakura.goguardian.com" } ], "post": { "tags": [ "Pusher Auth" ], "operationId": "pusherAuth", "summary": "Pusher channel authentication", "description": "Header Authorization (compRand). Query parameters: version, protocolVersion=1, capabilities (CSV of numeric capability bits — base [1,17,18,19,21] plus 2,20 on non-Windows and 3,4 on Windows), clientType=extension, os, liveStateVersion=6, plus the pusher channel_name and socket_id. Response {auth, channel_data} is ASSUMED — it is consumed inside the vendored pusher-js library, not visible to the extension code (uncertainty N1).", "x-evidence": "src/475-pusher.js:98-165, src/987-auth-endpoint.js:113-121, src/1642-live-state.js:364-433", "parameters": [ { "name": "version", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "protocolVersion", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 1 ] } }, { "name": "capabilities", "in": "query", "required": true, "schema": { "type": "string" }, "description": "CSV of numeric capability bits (1..22)." }, { "name": "clientType", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "extension" ] } }, { "name": "os", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "liveStateVersion", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 6 ] } }, { "name": "channel_name", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "socket_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pusher auth payload (shape assumed, consumed by vendored pusher-js).", "content": { "application/json": { "schema": { "type": "object", "properties": { "auth": { "type": "string" }, "channel_data": { "type": "string" } } } } } } } } }, "/v1/ext/sample": { "servers": [ { "url": "https://tivan.goguardian.com" } ], "post": { "tags": [ "Surveillance" ], "operationId": "uploadSample", "summary": "Evidence sample bundle upload (screenshot + JSON artifacts)", "description": "JSON {snapshotIds:[...], data:[{filename (\"screenshot.jpeg\" | \"content.json\" | \"prediction.json\" | \"metadata.json\"), dataURI}]}. On failure the sampler enters a 15-minute cooldown before retrying.", "x-evidence": "raw-modules/866.js:41-44", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleRequest" } } } }, "responses": { "200": { "description": "Response not read." } } } }, "/": { "description": "Shared root path: three distinct hosts serve \"/\" — the pre-signed S3 evidence bucket (POST), www.google.com (HEAD, clock sync), and blocked.goguardian.com (GET, generic block page). Each operation carries its own servers override, which OpenAPI 3.1 permits at the operation level.", "post": { "servers": [ { "url": "https://{bucket}.s3.amazonaws.com", "variables": { "bucket": { "description": "Evidence upload bucket from the sample descriptor." } } } ], "tags": [ "S3 Upload" ], "operationId": "s3MultipartUpload", "summary": "S3 multipart evidence upload (pre-signed, no auth headers)", "description": "security: [] — the auth is baked into the pre-signed form fields from the sample descriptor (descriptor.auth): Content-Type, key, policy, x-amz-algorithm, x-amz-credential, x-amz-date, x-amz-signature, plus the file field carrying the blob.", "x-evidence": "raw-modules/1011.js:9-34", "security": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "key", "policy", "x-amz-algorithm", "x-amz-credential", "x-amz-date", "x-amz-signature", "file" ], "properties": { "Content-Type": { "type": "string" }, "key": { "type": "string" }, "policy": { "type": "string" }, "x-amz-algorithm": { "type": "string" }, "x-amz-credential": { "type": "string" }, "x-amz-date": { "type": "string" }, "x-amz-signature": { "type": "string" }, "file": { "type": "string", "format": "binary", "description": "The evidence blob (screenshot or JSON artifact)." } } } } } }, "responses": { "200": { "description": "Response not read." } } }, "head": { "servers": [ { "url": "https://www.google.com" } ], "tags": [ "Utilities" ], "operationId": "syncClockFromGoogle", "summary": "Clock sync via Google Date header (no auth)", "description": "security: [] — HEAD https://www.google.com/ with timeout 5 s. Reads only the Date response header to correct the extension clock; on failure the system clock is trusted. Response body never consumed.", "x-evidence": "raw-modules/693.js:78-105", "security": [], "responses": { "200": { "description": "Only the Date header is read; body ignored.", "headers": { "Date": { "schema": { "type": "string" }, "description": "Server time used for clock sync." } } } } }, "get": { "servers": [ { "url": "https://blocked.goguardian.com" }, { "url": "https://staging.blocked.goguardian.com" } ], "tags": [ "Block Pages" ], "operationId": "showGenericBlockPage", "summary": "Generic admin/teacher/parent block page (no auth)", "description": "security: [] — opened as a tab (not XHR), so no auth headers. Path chosen by block reason: ADMIN_* / BLOCK_* / UNKNOWN reasons land here. Query ctx = base64(sorted URLSearchParams) with oi (orgID multiplied by 1234567), ou, st (sender tab type chromium-m|cip|na|shield|unknown), rs (reason enum string), sci, api, afi, pfi, x3rpi, tsi, tsfi, tsans (repeatable), v=1; required oi/ou/st/rs. Query sum = crc32(ctx) hex, padStart 8. The page validates by crc32 match, v < 8192, and oi positive and divisible by 1234567. Staging host is used when the extension build targets staging.", "x-evidence": "src/409-block-url.js:66-125, src/409-block-url.js:139-231, src/409-block-url.js:283-305", "security": [], "parameters": [ { "name": "ctx", "in": "query", "required": true, "schema": { "type": "string" }, "description": "base64 of the sorted, stringified URLSearchParams blob." }, { "name": "sum", "in": "query", "required": true, "schema": { "type": "string" }, "description": "crc32(ctx) as zero-padded 8-char hex." } ], "responses": { "200": { "description": "HTML block page (navigated to, not parsed as API).", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/ping": { "servers": [ { "url": "https://extension.goguardian.com" } ], "get": { "tags": [ "Utilities" ], "operationId": "nativeAgentPing", "summary": "Native-agent watchdog ping (no auth)", "description": "security: [] — no auth headers. Polled every 5 min while the native agent is healthy; expects HTTP 200 with body \"pong\". On failure the poll tightens to 10 s; 6 consecutive misses mark the native agent uninstalled, a body change triggers a reload of the agent, and the loop never runs on ChromeOS devices.", "x-evidence": "src/1517-native-agent-watcher.js:47-100", "security": [], "responses": { "200": { "description": "Literally the string \"pong\".", "content": { "text/plain": { "schema": { "type": "string", "enum": [ "pong" ] } } } } } } }, "/AccountChooser": { "servers": [ { "url": "https://accounts.google.com" } ], "get": { "tags": [ "Utilities" ], "operationId": "scrapeGoogleAccountChooser", "summary": "Google account name scrape (no auth, response not parsed)", "description": "security: [] — fetches the Google account chooser page to read the signed-in Google account name from the DOM in a separate context. The HTTP response is not consumed as an API. A sibling scrape GET https://myaccount.google.com/ (also security: [], response not consumed) reads the account name the same way; it shares this operation's path key spelling \"/\" with three other hosts, so it cannot carry its own path item in this document.", "x-evidence": "raw-modules/986.js:120", "security": [], "responses": { "200": { "description": "HTML page; response not consumed as API data." } } } }, "/parent/block.html": { "servers": [ { "url": "https://blocked.goguardian.com" }, { "url": "https://staging.blocked.goguardian.com" } ], "get": { "tags": [ "Block Pages" ], "operationId": "showParentBlockPage", "summary": "Parent site-filter block page (no auth)", "description": "security: [] — tab navigation, no auth headers. Reason mapping: PARENT_SITE_FILTER lands here. Same ctx/sum query contract as the generic block page.", "x-evidence": "src/409-block-url.js:66-125, src/409-block-url.js:139-231", "security": [], "parameters": [ { "name": "ctx", "in": "query", "required": true, "schema": { "type": "string" }, "description": "base64(sorted URLSearchParams): oi (orgID*1234567), ou, st, rs=PARENT_SITE_FILTER, v=1, optional sci/api/afi/pfi." }, { "name": "sum", "in": "query", "required": true, "schema": { "type": "string" }, "description": "crc32(ctx) hex padStart 8." } ], "responses": { "200": { "description": "HTML block page.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/parent/pause.html": { "servers": [ { "url": "https://blocked.goguardian.com" }, { "url": "https://staging.blocked.goguardian.com" } ], "get": { "tags": [ "Block Pages" ], "operationId": "showParentPausePage", "summary": "Parent pause / scheduled-pause page (no auth)", "description": "security: [] — tab navigation. Reason mapping: PARENT_PAUSE and PARENT_SCHEDULED_PAUSE land here. Same ctx/sum contract.", "x-evidence": "src/409-block-url.js:66-125, src/409-block-url.js:139-231", "security": [], "parameters": [ { "name": "ctx", "in": "query", "required": true, "schema": { "type": "string" }, "description": "base64(sorted URLSearchParams): oi, ou, st, rs=PARENT_PAUSE|PARENT_SCHEDULED_PAUSE, v=1." }, { "name": "sum", "in": "query", "required": true, "schema": { "type": "string" }, "description": "crc32(ctx) hex padStart 8." } ], "responses": { "200": { "description": "HTML pause page.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/teacher/block.html": { "servers": [ { "url": "https://blocked.goguardian.com" }, { "url": "https://staging.blocked.goguardian.com" } ], "get": { "tags": [ "Block Pages" ], "operationId": "showTeacherBlockPage", "summary": "Teacher scene block page (no auth)", "description": "security: [] — tab navigation. Reason mapping: TEACHER_SCENE lands here. Same ctx/sum contract, with tsi (teacherSceneId), tsfi (teacherSceneFilterId), and repeatable tsans in ctx.", "x-evidence": "src/409-block-url.js:66-125, src/409-block-url.js:139-231", "security": [], "parameters": [ { "name": "ctx", "in": "query", "required": true, "schema": { "type": "string" }, "description": "base64(sorted URLSearchParams): oi, ou, st, rs=TEACHER_SCENE, tsi, tsfi, tsans (repeatable), v=1." }, { "name": "sum", "in": "query", "required": true, "schema": { "type": "string" }, "description": "crc32(ctx) hex padStart 8." } ], "responses": { "200": { "description": "HTML block page.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/x3/block.html": { "servers": [ { "url": "https://blocked.goguardian.com" }, { "url": "https://staging.blocked.goguardian.com" } ], "get": { "tags": [ "Block Pages" ], "operationId": "showX3BlockPage", "summary": "Smart Alerts (X3) block page (no auth)", "description": "security: [] — tab navigation. Reason mapping: X3_REPORT lands here. ctx additionally carries x3rpi (x3ReportPublicId).", "x-evidence": "src/409-block-url.js:66-125, src/409-block-url.js:139-231", "security": [], "parameters": [ { "name": "ctx", "in": "query", "required": true, "schema": { "type": "string" }, "description": "base64(sorted URLSearchParams): oi, ou, st, rs=X3_REPORT, x3rpi, v=1." }, { "name": "sum", "in": "query", "required": true, "schema": { "type": "string" }, "description": "crc32(ctx) hex padStart 8." } ], "responses": { "200": { "description": "HTML block page with crisis resources.", "content": { "text/html": { "schema": { "type": "string" } } } } } } } }, "components": { "securitySchemes": { "CompRand": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Raw compRand token — NO \"Bearer\" prefix. Issued by POST /api/v1/ext/register, persisted at localStorage.compRand. Some hand-rolled fetches send it as the lowercase header \"authorization\"." }, "ExtensionVersion": { "type": "apiKey", "in": "header", "name": "ExtensionVersion", "description": "The extension's own version string. Hand-rolled fetches may send it lowercase (\"extensionversion\"); the X3 predictor pair uses X-GG-X3EXTVER instead." } }, "schemas": { "RegisterRequest": { "type": "object", "required": [ "orgRands" ], "properties": { "orgRands": { "type": "string" } }, "description": "jQuery form body (application/x-www-form-urlencoded)." }, "RegisterResponse": { "type": "object", "required": [ "compRand" ], "properties": { "compRand": { "type": "string", "description": "Session token stored at localStorage.compRand." } } }, "VersionRequest": { "type": "object", "required": [ "extVer" ], "properties": { "extVer": { "type": "string" } } }, "BypassResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "time": { "type": "number", "description": "Bypass window end (epoch ms)." } } }, "NameAndEmailRequest": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" } } }, "CreateAccountResponse": { "type": "object", "properties": { "message": { "type": "string" }, "success": { "type": "boolean" } } }, "GeolocationRequest": { "type": "object", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "description": "submitCoordsGuard.php form body; fire-and-forget." }, "UserResponse": { "type": "object", "required": [ "orgRand", "email" ], "properties": { "orgRand": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "orgId": { "type": "string" }, "name": { "type": "string" } }, "description": "Mismatch of orgRand/email against cached values wipes local state." }, "NameAndEmailSelectors": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, "PrivacyResponse": { "type": "object", "properties": { "apiMap": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional full-path -> host override map, installed with privacy settings; keyed by the complete path string (e.g. \"/api/v1/ext/policy\": \"https://alt.goguardian.com\")." } } }, "PolicyResponse": { "type": "object", "description": "Deliberately loose: the policy object is merged into settings wholesale. Known top-level groups include scene settings, YouTube category filters, smart-filtering config, off-task alerts, and feature flags." }, "ExperimentsResponse": { "type": "object", "properties": { "experiments": { "type": "object", "additionalProperties": true } } }, "NotificationsResponse": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "ChatMessagesResponse": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "DiagnoseRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string", "description": "JSON.stringify of a diagnostic state snapshot." } } }, "DeviceIdRequest": { "type": "object", "properties": { "deviceId": { "type": "string" } }, "description": "Plain-text response (dataType text) with the resolved device id." }, "ParticipantsResponse": { "type": "object", "properties": { "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } } } }, "Participant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "joinedAt": { "type": "number" } } }, "SnapshotResponse": { "type": "object", "required": [ "hash", "url" ], "properties": { "hash": { "type": "string", "description": "Must equal the client's md5 or the client throws \"hash mismatch!\"." }, "url": { "type": "string", "description": "Teacher-facing screenshot URL." } } }, "ActivitySnapshotRequest": { "type": "object", "required": [ "dataUrl", "seqId", "orgId", "subAccountId" ], "properties": { "dataUrl": { "type": "string", "description": "JPEG data URL", "quality 75.": null }, "seqId": { "type": "number" }, "orgId": { "type": "string" }, "subAccountId": { "type": "string" } } }, "LogsRequest": { "type": "object", "required": [ "logs", "submissionTime" ], "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string" }, "log": { "type": "string" }, "stack_trace": { "type": "string" }, "account_id": { "type": "string" }, "extension_version": { "type": "string" }, "os": { "type": "string" }, "org_id": { "type": "string" }, "sub_account_id": { "type": "string" } } } }, "submissionTime": { "type": "number" } }, "description": "Server re-serializes with Avro LogsBatch.Log (uncertainty N3)." }, "X3Prediction": { "type": "object", "properties": { "category": { "type": "string" }, "probability": { "type": "number" } } }, "X3ReportRequest": { "type": "object", "required": [ "url", "title", "timestamp", "sources", "prediction", "triggerIds" ], "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "imageId": { "type": "string", "nullable": true }, "timestamp": { "type": "number" }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "text", "image" ] } }, "prediction": { "type": "object", "properties": { "category": { "type": "string" }, "confidence": { "type": "number" } } }, "triggerIds": { "type": "array", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "type": "string" } } } }, "X3ReportResponse": { "type": "object", "properties": { "reportId": { "type": "string" }, "contentDescriptor": { "type": "string" }, "screenshotDescriptor": { "type": "string" }, "imageDescriptor": { "type": "string" } } }, "BeaconReportRequest": { "type": "object", "required": [ "url", "timestamp", "prediction", "closedMessage", "model" ], "properties": { "url": { "type": "string" }, "timestamp": { "type": "number" }, "prediction": { "type": "object", "additionalProperties": true }, "closedMessage": { "type": "boolean", "enum": [ false ] }, "didMessage": { "type": "boolean" }, "seqId": { "type": "number" }, "model": { "type": "string", "enum": [ "FULLPAGE_PREDICTOR", "TV_SEARCH_PREDICTOR" ] } } }, "BeaconReportResponse": { "type": "object", "properties": { "reportId": { "type": "string" }, "contentDescriptor": { "type": "string" }, "screenshotDescriptor": { "type": "string" } } }, "X3Policy": { "type": "object", "properties": { "triggers": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/X3Trigger" } }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/X3Trigger" } } } }, "blockedCategories": { "type": "array", "items": { "type": "string" }, "description": "Mapped internally to disabledCategories." }, "disabledImageFilteringSiteCategories": { "type": "array", "items": { "type": "string" } } } }, "X3Trigger": { "type": "object", "properties": { "triggerId": { "type": "string" }, "name": { "type": "string" }, "message": { "type": "string" }, "threshold": { "type": "number" }, "category": { "type": "string" }, "ou": { "type": "string" }, "triggerSources": { "type": "array", "items": { "type": "string" } }, "blockTarget": { "type": "string" } } }, "BeaconPolicy": { "type": "object", "description": "Deployment/feature payload cached under key \"beacon\"; exact fields not reconstructed. HTTP 400 with code 9 means not deployed." }, "BeaconPrediction": { "type": "object", "properties": { "phase": { "type": "string" }, "probability": { "type": "number" } } }, "SampleRequest": { "type": "object", "required": [ "snapshotIds", "data" ], "properties": { "snapshotIds": { "type": "array", "items": { "type": "string" } }, "data": { "type": "array", "items": { "type": "object", "required": [ "filename", "dataURI" ], "properties": { "filename": { "type": "string", "enum": [ "screenshot.jpeg", "content.json", "prediction.json", "metadata.json" ] }, "dataURI": { "type": "string" } } } } } }, "EntityBatchPreAuthRecord": { "type": "object", "description": "INFORMATIONAL — the decoded Avro record inside the gzipped application/binary body of POST /v1/entitybatchpreauth (schema version 13). See EntityPreAuth for the per-entity payload.", "required": [ "type", "compRand", "submissionTime", "extensionVersion", "payload" ], "properties": { "type": { "type": "string", "enum": [ "ENTITIES" ] }, "compRand": { "type": "string" }, "submissionTime": { "type": "integer", "format": "int64" }, "extensionVersion": { "type": "string" }, "userAgent": { "type": "string" }, "ip": { "type": "integer", "format": "int64", "description": "IPv4 packed as 256*(256*(256*a+b)+c)+d." }, "deviceId": { "type": [ "string", "null" ] }, "payload": { "type": "array", "items": { "$ref": "#/components/schemas/EntityPreAuth" } } } }, "EntityPreAuth": { "type": "object", "description": "INFORMATIONAL — per-entity Avro record. FlaggedActivity, searches (deprecated), videos, docs, blockedSite, viewings, tabs are the substantive surveillance fields; keyFlags is always [] as of src/1736; sourceType defaults to 0.", "properties": { "seqId": { "type": "integer", "format": "int64" }, "url": { "type": "string" }, "flaggedActivity": { "type": "array", "items": { "type": "object", "properties": { "isNew": { "type": "boolean" }, "severity": { "type": "number" }, "image": { "type": [ "string", "null" ] }, "categoryId": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "object", "properties": { "term": { "type": "string" }, "count": { "type": "integer" }, "severity": { "type": "number" }, "calculatedSeverity": { "type": "number" } } } } } } }, "keyFlags": { "type": "array", "description": "Always empty as of src/1736.", "items": { "type": "object" } }, "searches": { "type": "array", "deprecated": true, "items": { "type": "object", "properties": { "isNew": { "type": "boolean" }, "searchTerms": { "type": "string" } } } }, "videos": { "type": "array", "items": { "type": "object", "properties": { "isNew": { "type": "boolean" }, "title": { "type": "string" }, "uploader": { "type": "string" }, "categoryId": { "type": "integer" }, "rating": { "type": "integer" }, "description": { "type": "string" }, "channelId": { "type": "string" }, "category": { "type": "string" }, "uri": { "type": "string" }, "videoId": { "type": "string" }, "type": { "type": "string", "enum": [ "YOUTUBE" ] }, "blockMetadata": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "ADMIN_YOUTUBE_CATEGORY", "ADMIN_YOUTUBE_CHANNEL", "ADMIN_YOUTUBE_KEYWORD", "ADMIN_YOUTUBE_VIDEO", "ADMIN_YOUTUBE_AGE_RESTRICTION", "ADMIN_YOUTUBE_SAFE_MODE", "UNKNOWN" ] }, "adminPolicyId": { "type": [ "integer", "null" ], "format": "int64" }, "adminFilterId": { "type": [ "integer", "null" ], "format": "int64" } } } ] }, "adminPolicyOverrideVideoId": { "type": [ "integer", "null" ], "format": "int64" } } } }, "docs": { "type": "array", "items": { "type": "object", "properties": { "isNew": { "type": "boolean" }, "title": { "type": "string" } } } }, "faviconUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "tabId": { "type": [ "integer", "null" ] }, "blockedSite": { "type": "array", "items": { "type": "object", "properties": { "isNew": { "type": [ "boolean", "null" ] }, "categoryId": { "type": "integer" }, "originalUrl": { "type": [ "string", "null" ] }, "reason": { "oneOf": [ { "type": "null" }, { "type": "string", "enum": [ "BLOCK_WEB_PROXIES", "BLOCK_DIRECT_IP_ACCESS", "ADMIN_SITE_FILTER", "ADMIN_SITE_CATEGORY_FILTER", "ADMIN_SAFE_MODE", "PARENT_SITE_FILTER", "PARENT_PAUSE", "PARENT_SCHEDULED_PAUSE", "X3_REPORT", "TEACHER_SCENE", "UNKNOWN", "BLOCK_CONSUMER_ACCOUNTS" ] } ] }, "adminPolicyId": { "type": "integer", "format": "int64" }, "adminFilterId": { "type": "integer", "format": "int64" }, "parentFilterId": { "type": "integer", "format": "int64" }, "x3ReportPublicId": { "type": [ "string", "null" ] }, "teacherSceneId": { "type": [ "integer", "null" ], "format": "int64" }, "teacherSceneFilterId": { "type": [ "integer", "null" ], "format": "int64" } } } }, "viewings": { "type": "array", "items": { "type": "object", "properties": { "startTimeMs": { "type": "integer", "format": "int64" }, "endTimeMs": { "type": "integer", "format": "int64" }, "isDirty": { "type": "boolean" }, "lastSubmissionTimeMs": { "type": [ "integer", "null" ], "format": "int64" } } } }, "isNew": { "type": [ "boolean", "null" ] }, "classroomIds": { "type": "array", "items": { "type": "integer" } }, "classroomSessionIds": { "type": "array", "items": { "type": "integer" } }, "isLocked": { "type": [ "boolean", "null" ] }, "tabs": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "faviconUrl": { "type": "string" }, "isActive": { "type": "boolean" }, "id": { "type": "integer" } } } }, "isProxy": { "type": [ "boolean", "null" ] }, "sourceType": { "type": "integer", "default": 0 }, "tivanIds": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "beaconIds": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "offTaskScores": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Keyed \"-\"." }, "dataScienceTags": { "type": "object", "additionalProperties": { "type": "string" } }, "clientSettings": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "admin": { "type": [ "boolean", "null" ] }, "teacher": { "type": [ "boolean", "null" ] } } } ] }, "adminPolicyOverrideId": { "type": [ "integer", "null" ], "format": "int64" }, "x3ReportPublicIds": { "type": "array", "items": { "type": "string" } }, "containsImageBlock": { "type": [ "boolean", "null" ] } } } } } }