Developers

Build integrations and custom clients with the Screenie API

Introduction

Screenie provides a fully-featured REST API for building client timer apps, accessing family screen time allowances, and integrating with external systems. Whether you're building a dedicated device, a mobile app, or connecting Screenie to your smart home setup, our API has you covered.

Example Use Cases

Build a tiny timer that displays remaining screen time
Create a smartwatch or phone app that tracks screen time
Update an external display (e.g. e-ink screen, LED matrix) with current screen time allowances
Integrate with third-party screen time providers or parental control systems
Connect to smart home platforms — for example, automatically disable internet access when screen time has run out
Build custom dashboards or reporting tools for screen time analytics

Authentication

Parent Access Role (API Key)

To access admin-related functions — such as reading and writing screen time allowances, accepting bonus time requests, and managing family members — you'll need to obtain an API key.

API keys can be generated from your Settings page. Once you have your key, include it in the request header:

header

X-API-Key: your-api-key-here

Keep your API key secure. Never expose it in client-side code or public repositories.

Device Pairing Process

Child Access Role (Device Token)

For headless devices like timers, smart TV apps, or IoT displays, Screenie provides an automated pairing flow. This allows a device to obtain an API token without requiring direct user login on the device itself — instead, a parent authorizes the device by scanning a QR code or entering a pairing code on their phone or computer.

Step-by-Step Pairing Flow

Device Requests a Pairing Code

The device calls the pairing endpoint to obtain a unique code:

http

GET /api/pairing/devicecode?deviceName=Living%20Room%20Timer

Response:
{
  "pairingCode": "ABC123",
  "expiresAt": "2026-01-04T15:30:00.000Z",
  "pollInterval": 5
}

Device Displays the Code

The device then displays the pairing code to the user. You have two options:

Option A: QR Code

Generate a QR code that links directly to the pairing page with the code embedded:

url

https://screenie.org/home/pair?code=ABC123

Option B: Manual Entry

Display the code on screen along with instructions for the user to visit https://screenie.org/home/pair and enter the code manually.

Parent Authorizes the Device

The parent scans the QR code or visits the pairing page and enters the code. They'll be prompted to log in (if not already) and then confirm the pairing.

Device Polls for Completion

While waiting for authorization, the device should poll at the recommended interval (returned in the initial response) to check if pairing is complete:

http

GET /api/pairing/devicecode/status?code=ABC123

// When still waiting:
{ "status": "pending" }

// When authorized:
{
  "status": "linked",
  "apiKey": "device-api-key-xxxxx",
  "familyGroupId": "abc123...",
  "childId": "def456..."
}

Device Stores Credentials

Once the API key is received, the device should securely store it for future API calls. The device can now access screen time data for the linked family using the X-API-Key header.

Getting Started

API Base URL

url

https://screenie.org/api

All API responses are returned in JSON format. Standard HTTP status codes indicate success (2xx) or failure (4xx, 5xx).

Example API Calls

Get User's Family Groups

GET/api/family

Retrieve all family groups where the authenticated user is a parent.

bash

curl -X GET "https://screenie.org/api/family" \
  -H "X-API-Key: your-api-key-here"

Get Family Members

GET/api/family/{familyGroupId}

Retrieve all members of a specific family group, including children and their details.

bash

curl -X GET "https://screenie.org/api/family/abc123" \
  -H "X-API-Key: your-api-key-here"

Get Child's Screen Time Allowance

GET/api/family/{familyGroupId}/child/{childId}/screentime/allowances

Retrieve the base screen time allowance settings for a specific child.

bash

curl -X GET "https://screenie.org/api/family/abc123/child/def456/screentime/allowances" \
  -H "X-API-Key: your-api-key-here"

Get Effective Allowance for Today

GET/api/family/{familyGroupId}/child/{childId}/screentime/on-date/today

Get the calculated screen time for a specific date, including any bonus time grants.

bash

curl -X GET "https://screenie.org/api/family/abc123/child/def456/screentime/on-date/today?includegrants=true" \
  -H "X-API-Key: your-api-key-here"

Grant Bonus Screen Time

POST/api/family/{familyGroupId}/child/{childId}/grant

Add bonus minutes to a child's screen time for a specific date.

bash

curl -X POST "https://screenie.org/api/family/abc123/child/def456/grant" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "applicableDate": "today",
    "bonusMinutes": 30,
    "notes": "Great homework completion!"
  }'

Record a Screen Time Session

POST/api/family/{familyGroupId}/child/{childId}/session

Log consumed screen time by recording a session with start time and duration.

bash

curl -X POST "https://screenie.org/api/family/abc123/child/def456/session" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "startedAt": "2026-01-04T14:00:00.000Z",
    "duration": 45
  }'

Further Reference

For a complete guide to all available endpoints, request/response schemas, and advanced features, check out the full API documentation.

API Documentation

Comprehensive reference for all Screenie API endpoints.

Need Help?

If you have questions about the API or need assistance with your integration, we're here to help.

Learn More About Screenie