Docs
Status
Supportk-id.comCompliance Studio
Endpoints스크린타임

스크린타임 예외 요청

아이가 오늘 시간을 더 쓰고 싶거나 적용 중인 조용한 시간(quiet hours)을 넘기고 싶을 때, 아이를 대신해 예외 요청을 전송합니다. k-ID는 요청을 기록하고 승인 또는 거부를 위해 보호자에게 알립니다. 아이별로 멱등적이며, 같은 아이의 다른 요청이 아직 보류 중일 때 호출하면 두 번째 요청을 만들지 않고 그 보류 중인 요청을 그대로 반환합니다. 결정 결과는 `status: "granted" | "denied" | "expired"`를 담은 단일 `Screentime.OverrideResult` 웹훅으로 비동기적으로 전달됩니다. 웹훅 본문은 `state` 아래에 `GET /screentime/get-state`와 동일한 형식을 담고 있어, 플랫폼이 추가 조회 없이 보관 중인 상태를 바로 갱신할 수 있습니다. 24시간 내에 해결되지 않은 요청은 `status: "expired"`로 웹훅을 발생시킵니다.

POST
/screentime/request-override

Authorization

api-key
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"}

세션의 완료된 스크린타임 사용 구간 전송 POST

k-ID 세션에 대해 완료된 스크린타임 사용 구간을 하나 이상 전송합니다. 각 이벤트는 사용이 언제 시작되어 얼마나 이어졌는지를 기록합니다. 사용 시간을 사후에만 알 수 있는 경우(구간을 버퍼링해 주기적으로 업로드하는 백엔드, 종료 시점에 세션 합계를 보고하는 게임 엔진 등)에 이 API를 사용하십시오. 수락된 각 구간의 `durationSeconds`는 플레이어의 당일 스크린타임 합계에 더해집니다. 구간이 보호자가 설정한 타임존에서 자정을 넘기면 두 날짜로 분할되어, 각 날짜의 합계가 실제로 그날 발생한 사용량을 반영합니다. 이벤트는 각각 독립적으로 처리됩니다. 응답에는 이벤트별 상태가 담깁니다. * `accepted` - 구간이 기록되어 당일 합계에 반영되었습니다. 이미 수락된 `id`를 가진 이벤트를 다시 전송해도 안전한 무동작으로 처리되어 다시 `accepted`로 집계되고 중복 반영되지 않으므로, 네트워크 장애 후 재시도로 이중 집계되지 않습니다. * `rejected` - 구간이 검증을 통과하지 못했습니다. `reason`이 어떤 규칙에 걸렸는지 알려줍니다. 세션이 존재하지 않거나 무효화된 경우에는 배치 전체가 거부됩니다. 실시간 적용 신호(`Screentime.LimitWarning`, `Screentime.LimitReached`, `Screentime.BreakReminder`)는 이 API에서 발생하지 않습니다. 임계값을 넘는 시점에 이러한 웹훅이 발생해야 하는 연동에서는 `/screentime/start`와 `/screentime/end`를 사용하십시오.

스크린타임 시작 POST

이 제품에서 활성 스크린타임의 시작을 기록합니다. 스크린타임이 활성인 동안 k-ID는 실시간 웹훅(`Screentime.BreakReminder`, `Screentime.LimitWarning`, `Screentime.LimitReached`)을 전달합니다. 이 웹훅은 사용이 끝날 때만이 아니라 임계값을 넘는 시점에 발생합니다. 상태 의미: * `accepted` - 스크린타임이 시작되었거나, 이미 활성인 세션에 대한 재시도가 멱등적으로 처리되었습니다. * `replaced` - 이 `sessionId`에서 스크린타임이 이미 활성인 상태로 다른 `id`가 전송되었습니다. 이전 스크린타임은 자동으로 종료되고 그 시간은 당일 스크린타임 사용량에 반영되었습니다. 이전 스크린타임이 명시적으로 종료되지 않은 경우(앱이나 기기 재시작 등)를 복구하는 데 사용할 수 있습니다. 하나의 `sessionId`에는 동시에 하나의 활성 스크린타임만 지원됩니다. 호출은 실시간으로 이루어져야 하며, `timestamp` 값은 5분보다 이전일 수 없습니다.