Endpoints스크린타임

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

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

POST
/screentime/push
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/screentime/push" \  -H "Content-Type: application/json" \  -d '{    "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",    "events": [      {        "id": "9d4e2f81-7a3b-4c56-8e90-1f2a3b4c5d6e",        "durationSeconds": 1800,        "timestamp": "2026-06-24T09:00:00Z"      },      {        "id": "c1b2a3d4-5e6f-4708-9a1b-2c3d4e5f6071",        "durationSeconds": 2400,        "timestamp": "2026-06-24T13:00:00Z"      }    ]  }'
{  "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",  "accepted": 2,  "rejected": 0,  "events": [    {      "id": "9d4e2f81-7a3b-4c56-8e90-1f2a3b4c5d6e",      "status": "accepted"    },    {      "id": "c1b2a3d4-5e6f-4708-9a1b-2c3d4e5f6071",      "status": "accepted"    }  ]}

스크린타임 상태 조회 GET

`sessionId`의 현재 스크린타임 상태를 반환합니다. 보호자가 설정한 규칙, 오늘의 사용량, 그리고 지금 플레이를 허용해도 되는지 여부가 포함됩니다. 플랫폼은 세션 시작 시점과 `Screentime.LimitWarning`, `Screentime.LimitReached`, `Screentime.QuietHoursWarning`, `Screentime.QuietHoursReached` 웹훅을 받은 뒤에 보관 중인 상태를 갱신하기 위해 이 API를 호출합니다. 보호자가 해당 세션에 스크린타임을 설정하지 않았거나, 설정했더라도 적용을 비활성화한 경우에는 `{ "enabled": false }`를 반환합니다.

스크린타임 예외 요청 POST

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