EndpointsScreentime

Request a screentime override

Submits an override request on the kid's behalf when they want more time today or to bypass active quiet hours. k-ID records the request and notifies the parent to approve or deny. Idempotent per kid: a call made while another request from the same kid is still pending returns that pending request unchanged rather than creating a second one. The resolution arrives asynchronously as a single `Screentime.OverrideResult` webhook with `status: "granted" | "denied" | "expired"`. The webhook body carries the same shape as `GET /screentime/get-state` under `state`, so the platform can update its copy of the state directly without a follow-up fetch. Requests that aren't resolved within 24 hours fire the webhook with `status: "expired"`.

POST
/screentime/request-override
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The kid's session the override is being requested for.

Response Body

application/json

application/json

curl -X POST "https://example.com/screentime/request-override" \  -H "Content-Type: application/json" \  -d '{    "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672"  }'
{  "id": "9d4e2f81-7a3b-4c56-8e90-1f2a3b4c5d6e",  "expiresAt": "2026-06-25T16:00:00Z"}

Submit completed screentime usage segments for a session POST

Submit one or more completed segments of screentime usage for a k-ID session. Each event records when a span of usage began and how long it lasted. Use this endpoint when usage is known only after the fact - for example, a backend that buffers segments and uploads them periodically, or a game engine that reports session totals on shutdown. Each accepted segment adds its `durationSeconds` to the player's daily screentime total. If a segment crosses midnight in the parent's configured timezone, it is split across both dates so each day's total reflects the usage that actually happened on that date. Events are processed independently. The response carries a per-event status: * `accepted` - the segment was recorded and added to the daily total. Resubmitting an event whose `id` was already accepted is a safe no-op: it counts as `accepted` again and is not added twice, so retries after a network failure won't double-count. * `rejected` - the segment failed validation; the `reason` identifies which rule. The whole batch is rejected when the session does not exist or is revoked. Real-time enforcement signals (`Screentime.LimitWarning`, `Screentime.LimitReached`, `Screentime.BreakReminder`) are not fired from this endpoint. Use `/screentime/start` + `/screentime/end` for integrations that need those webhooks to fire at the moment a threshold is crossed.

Start screentime POST

Marks the start of active screentime on this product. While screentime is active, k-ID delivers real-time webhooks - `Screentime.BreakReminder`, `Screentime.LimitWarning`, and `Screentime.LimitReached` - that fire at the moment a threshold is crossed, not only when usage ends. Status semantics: * `accepted` - screentime was started, or a retried call against an already-active session was absorbed idempotently. * `replaced` - a different `id` was sent while screentime was already active for this `sessionId`; the prior screentime was automatically ended and its duration counted toward today's screentime usage. Use this to recover when the prior screentime was never explicitly ended (e.g. after an app or device restart). Only one active screentime is supported per `sessionId` at a time. Calls must be made in real time - the `timestamp` value cannot be more than 5 minutes in the past.