Phosra

Phosra Child Safety Spec (PCSS) v1.0

This document defines the Phosra Child Safety Spec (PCSS), an open technical framework for technology platforms that serve minors. Platforms SHOULD implement this spec to align with emerging child safety regulations and industry best practices.

PCSS establishes a universal policy framework spanning 104 safety categories across 19 domains: Content, Time, Purchase, Social, Web, Privacy, Monitoring, Algorithmic Safety, Notifications, Advertising & Data, Access Control, Age Assurance, AI Safety, CSM Content Ratings, CSM Privacy Ratings, Platform Accountability, and School / Literacy. Platforms SHALL expose compliance endpoints that accept policy enforcement requests from the Phosra Enforcement Engine.

This spec is published by Phosra and designed to align with current and emerging child safety regulations. Platforms adopting this spec position themselves ahead of regulatory requirements.

104

Policy Categories

5

Rating Systems

15

Regulated Platforms

3

Compliance Levels

RFC 2119 Keywords

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

MUST / REQUIRED / SHALL — Absolute requirement
SHOULD / RECOMMENDED — Strong recommendation, may be deviated from with justification
MAY / OPTIONAL — Truly optional behavior
MUST NOT / SHALL NOT — Absolute prohibition

1. Platform Authentication

All regulated platforms MUST authenticate using JWT bearer tokens. The authentication system implements refresh token rotation with SHA-256 hashing for security.

Access Token

Platforms MUST include a valid JWT in the Authorization header. Tokens expire after 15 minutes.

Authorization: Bearer <access_token>

Token Rotation

Platforms MUST implement token rotation. Each refresh request returns a new token pair and revokes the previous refresh token. Platforms MUST NOT reuse expired refresh tokens.

POST/auth/register

Create a new user account. Returns the user object and a token pair (access + refresh). The access token expires in 15 minutes; use the refresh endpoint to obtain a new one.

Request fields

email

Valid email address

stringrequired
password

Minimum 8 characters

stringrequired
name

Display name

stringrequired

Response fields

user

Created user

object
tokens

JWT token pair

object
Requestcurl
curl -X POST https://api.phosra.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "parent@example.com",
    "password": "securepass123",
    "name": "Jane Parent"
  }'
Responsejson
{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "parent@example.com",
    "name": "Jane Parent",
    "created_at": "2025-01-15T10:30:00Z"
  },
  "tokens": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
    "expires_at": "2025-01-15T10:45:00Z"
  }
}
POST/auth/login

Authenticate with email and password. Returns a user object and token pair. Previous refresh tokens remain valid until explicitly revoked via logout.

Request fields

email

Registered email address

stringrequired
password

Account password

stringrequired

Response fields

user

Authenticated user

object
tokens

JWT token pair

object
Requestcurl
curl -X POST https://api.phosra.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "parent@example.com",
    "password": "securepass123"
  }'
Responsejson
{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "parent@example.com",
    "name": "Jane Parent",
    "created_at": "2025-01-15T10:30:00Z"
  },
  "tokens": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
    "expires_at": "2025-01-15T10:45:00Z"
  }
}
POST/auth/refresh

Exchange a valid refresh token for a new token pair. The old refresh token is revoked (rotation). No Authorization header required.

Request fields

refresh_token

Valid refresh token from login or previous refresh

stringrequired

Response fields

access_token

JWT access token (15 min TTL)

string
refresh_token

Refresh token for obtaining new access tokens

string
expires_at

Access token expiration timestamp

datetime
Requestcurl
curl -X POST https://api.phosra.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
  }'
Responsejson
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "bmV3IHJlZnJlc2ggdG9r...",
  "expires_at": "2025-01-15T11:00:00Z"
}
POST/auth/logout

Revoke all refresh tokens for the current user. The access token remains valid until its TTL expires (15 min). Requires a valid access token.

Requestcurl
curl -X POST https://api.phosra.com/api/v1/auth/logout \
  -H "Authorization: Bearer <access_token>"
Responsejson
// 204 No Content
GET/auth/me

Return the authenticated user's profile. Requires a valid access token.

Response fields

id

Unique user identifier

uuid
email

User email address

string
name

User display name

string
created_at

Account creation timestamp

datetime
Requestcurl
curl https://api.phosra.com/api/v1/auth/me \
  -H "Authorization: Bearer <access_token>"
Responsejson
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "parent@example.com",
  "name": "Jane Parent",
  "created_at": "2025-01-15T10:30:00Z"
}

2. Protected Families

The family data model SHALL support multiple guardians per family unit with role-based access control. Child profiles MUST include birth date for age-based policy computation.

Owner

Full administrative control. MAY delete the family unit.

Parent

MAY manage children, policies, and compliance links.

Guardian

Read-only access. MUST NOT modify policies or compliance links.

GET/families

Return all families the authenticated user belongs to, including families where the user is owner, parent, or guardian.

Response fields

[]

Array of family objects

Family[]
Requestcurl
curl https://api.phosra.com/api/v1/families \
  -H "Authorization: Bearer <access_token>"
Responsejson
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Smith Family",
    "created_at": "2025-01-10T08:00:00Z"
  }
]
POST/families

Create a new family group. The authenticated user becomes the owner automatically. A user can belong to multiple families.

Request fields

name

Family display name

stringrequired

Response fields

id

Family identifier

uuid
name

Family display name

string
created_at

Family creation timestamp

datetime
Requestcurl
curl -X POST https://api.phosra.com/api/v1/families \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Smith Family" }'
Responsejson
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Smith Family",
  "created_at": "2025-01-10T08:00:00Z"
}
GET/families/{familyID}

Retrieve details of a specific family. Caller must be a member of the family.

Response fields

id

Family identifier

uuid
name

Family display name

string
created_at

Family creation timestamp

datetime
Requestcurl
curl https://api.phosra.com/api/v1/families/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <access_token>"
Responsejson
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Smith Family",
  "created_at": "2025-01-10T08:00:00Z"
}
PUT/families/{familyID}

Update family properties. Only the family owner can perform updates.

Request fields

name

New family display name

string
Requestcurl
curl -X PUT https://api.phosra.com/api/v1/families/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Smith-Jones Family" }'
Responsejson
// 200 OK
DELETE/families/{familyID}

Permanently delete a family and all associated children, policies, and connections. Only the family owner can delete. This action cannot be undone.

Requestcurl
curl -X DELETE https://api.phosra.com/api/v1/families/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <access_token>"
Responsejson
// 204 No Content
GET/families/{familyID}/children

List all children belonging to a family. Caller must be a family member.

Response fields

[]

Array of child objects

Child[]
Requestcurl
curl https://api.phosra.com/api/v1/families/a1b2c3d4-e5f6-7890-abcd-ef1234567890/children \
  -H "Authorization: Bearer <access_token>"
Responsejson
[
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "family_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Alex",
    "birth_date": "2015-06-20",
    "avatar_url": null,
    "created_at": "2025-01-10T08:15:00Z"
  }
]
POST/families/{familyID}/children

Add a child to a family. The birth date is used for age-based policy generation and content rating calculations.

Request fields

name

Child display name

stringrequired
birth_date

Date of birth in YYYY-MM-DD format

daterequired

Response fields

id

Child identifier

uuid
family_id

Parent family identifier

uuid
name

Child display name

string
birth_date

Date of birth (YYYY-MM-DD)

date
avatar_url

Optional avatar URL

string
created_at

Record creation timestamp

datetime
Requestcurl
curl -X POST https://api.phosra.com/api/v1/families/a1b2c3d4-e5f6-7890-abcd-ef1234567890/children \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex",
    "birth_date": "2015-06-20"
  }'
Responsejson
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "family_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Alex",
  "birth_date": "2015-06-20",
  "avatar_url": null,
  "created_at": "2025-01-10T08:15:00Z"
}
GET/children/{childID}

Retrieve details of a specific child. Caller must be a member of the child's family.

Response fields

id

Child identifier

uuid
family_id

Parent family identifier

uuid
name

Child display name

string
birth_date

Date of birth (YYYY-MM-DD)

date
avatar_url

Optional avatar URL

string
created_at

Record creation timestamp

datetime
Requestcurl
curl https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer <access_token>"
Responsejson
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "family_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Alex",
  "birth_date": "2015-06-20",
  "avatar_url": null,
  "created_at": "2025-01-10T08:15:00Z"
}
PUT/children/{childID}

Update a child's profile. Only family members with parent or owner role can update.

Request fields

name

Updated display name

string
birth_date

Updated date of birth

date
Requestcurl
curl -X PUT https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Alexander" }'
Responsejson
// 200 OK
DELETE/children/{childID}

Remove a child and all associated policies and sync history. Only the family owner can delete children.

Requestcurl
curl -X DELETE https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer <access_token>"
Responsejson
// 204 No Content
GET/children/{childID}/age-ratings

Return age-appropriate content ratings for a child across all supported rating systems (MPAA, TV Parental Guidelines, ESRB, PEGI, Common Sense Media). Calculated from the child's birth date.

Response fields

age

Child's current age in years

integer
ratings

Map of rating system ID to maximum allowed rating

object
Requestcurl
curl https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901/age-ratings \
  -H "Authorization: Bearer <access_token>"
Responsejson
{
  "age": 10,
  "ratings": {
    "mpaa": {
      "code": "PG",
      "name": "Parental Guidance Suggested",
      "min_age": 8
    },
    "tv": {
      "code": "TV-PG",
      "name": "Parental Guidance Suggested",
      "min_age": 8
    },
    "esrb": {
      "code": "E10+",
      "name": "Everyone 10+",
      "min_age": 10
    },
    "pegi": {
      "code": "PEGI 12",
      "name": "PEGI 12",
      "min_age": 12
    },
    "csm": {
      "code": "10+",
      "name": "Age 10+",
      "min_age": 10
    }
  }
}

2.1 Family Members

Families support multi-guardian access with role-based permissions. Members MAY be added to share access to children, policies, and enforcement controls. The family data model supports co-parenting, caregiver delegation, and institutional use cases.

Owner

Full administrative control. MAY add/remove members, manage all policies, and delete the family.

Parent

MAY manage children, modify policies, trigger enforcement, and view reports.

Guardian

Read-only access. MAY view policies and reports. MUST NOT modify rules.

GET/families/{familyID}/members

List all members of a family with their roles and permissions. Roles include owner (full admin), parent (manage children and policies), and guardian (read-only access).

Response fields

[]

Array of family member objects

Member[]
Requestcurl
curl https://api.phosra.com/api/v1/families/a1b2c3d4-e5f6-7890-abcd-ef1234567890/members \
  -H "Authorization: Bearer <access_token>"
Responsejson
[
  {
    "id": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "family_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "role": "owner",
    "email": "parent@example.com",
    "name": "Jane Parent",
    "joined_at": "2025-01-10T08:00:00Z"
  }
]
POST/families/{familyID}/members

Invite a user to join a family. The invited user must have an existing Phosra account. Only the family owner can add new members. Supported roles: parent, guardian.

Request fields

email

Email address of the user to invite

stringrequired
role

One of: parent, guardian

enumrequired

Response fields

id

Member record identifier

uuid
user_id

User account identifier

uuid
family_id

Family identifier

uuid
role

One of: owner, parent, guardian

enum
email

Member email address

string
name

Member display name

string
joined_at

When the member joined the family

datetime
Requestcurl
curl -X POST https://api.phosra.com/api/v1/families/a1b2c3d4-e5f6-7890-abcd-ef1234567890/members \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "coparent@example.com",
    "role": "parent"
  }'
Responsejson
{
  "id": "m2b3c4d5-e6f7-8901-bcde-f12345678901",
  "user_id": "660e8400-e29b-41d4-a716-446655440001",
  "family_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "role": "parent",
  "email": "coparent@example.com",
  "name": "John Co-Parent",
  "joined_at": "2025-01-12T14:30:00Z"
}
DELETE/families/{familyID}/members/{memberID}

Remove a member from a family. Only the family owner can remove members. The owner cannot remove themselves — use Delete Family instead. Removed members immediately lose access to all family data.

Requestcurl
curl -X DELETE https://api.phosra.com/api/v1/families/a1b2c3d4-e5f6-7890-abcd-ef1234567890/members/m2b3c4d5-e6f7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer <access_token>"
Responsejson
// 204 No Content

3. Safety Policies

Safety policies define protection rules for each child. Each policy contains rules across 104 categories spanning 19 domains. Platforms MUST implement enforcement for all categories they claim capability in. Rules are stored as JSONB with category-specific schemas.

Policies transition through states: draft →active →paused. Only active policies SHALL be enforced on platforms.

GET/children/{childID}/policies

List all safety policies for a child, ordered by priority. Each child can have multiple policies (e.g. weekday vs weekend).

Response fields

[]

Array of policy objects

Policy[]
Requestcurl
curl https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901/policies \
  -H "Authorization: Bearer <access_token>"
Responsejson
[
  {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "child_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "School Days",
    "status": "active",
    "priority": 1,
    "created_at": "2025-01-10T09:00:00Z"
  }
]
POST/children/{childID}/policies

Create a new safety policy for a child. The policy starts in draft status. Add rules, then activate it to begin enforcement.

Request fields

name

Policy display name (e.g. "School Days", "Weekend")

stringrequired

Response fields

id

Policy identifier

uuid
child_id

Associated child identifier

uuid
name

Policy display name

string
status

One of: active, paused, draft

enum
priority

Evaluation priority (lower = higher precedence)

integer
created_at

Policy creation timestamp

datetime
Requestcurl
curl -X POST https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901/policies \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "School Days" }'
Responsejson
{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "child_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "name": "School Days",
  "status": "draft",
  "priority": 1,
  "created_at": "2025-01-10T09:00:00Z"
}
POST/policies/{policyID}/activate

Transition a policy from draft or paused to active. An active policy's rules will be enforced on the next sync. Only one policy per child can be active at a time; activating one pauses others.

Requestcurl
curl -X POST https://api.phosra.com/api/v1/policies/c3d4e5f6-a7b8-9012-cdef-123456789012/activate \
  -H "Authorization: Bearer <access_token>"
Responsejson
// 200 OK
POST/policies/{policyID}/pause

Pause an active policy. Rules remain configured but will not be enforced until reactivated. Pausing does not remove already-pushed rules from providers.

Requestcurl
curl -X POST https://api.phosra.com/api/v1/policies/c3d4e5f6-a7b8-9012-cdef-123456789012/pause \
  -H "Authorization: Bearer <access_token>"
Responsejson
// 200 OK
POST/policies/{policyID}/generate-from-age

Automatically generate a full set of policy rules based on the child's current age. Uses the built-in age-to-setting mapping across all 104 rule categories (47 baseline + 57 CSM-aligned). Existing rules on the policy are replaced.

Response fields

[]

Generated rules

PolicyRule[]
Requestcurl
curl -X POST https://api.phosra.com/api/v1/policies/c3d4e5f6-a7b8-9012-cdef-123456789012/generate-from-age \
  -H "Authorization: Bearer <access_token>"
Responsejson
[
  {
    "id": "d4e5f6a7-b8c9-0123-def0-123456789abc",
    "policy_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "category": "web_filtering",
    "enabled": true,
    "config": {
      "block_categories": [
        "adult",
        "gambling",
        "violence"
      ]
    },
    "created_at": "2025-01-10T09:05:00Z"
  },
  {
    "id": "e5f6a7b8-c9d0-1234-ef01-23456789abcd",
    "policy_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "category": "screen_time",
    "enabled": true,
    "config": {
      "daily_limit_minutes": 120,
      "bedtime": "21:00"
    },
    "created_at": "2025-01-10T09:05:00Z"
  }
]
GET/policies/{policyID}/rules

List all rules in a policy. Rules are returned in category order across all 104 supported categories.

Response fields

[]

Array of rule objects

PolicyRule[]
Requestcurl
curl https://api.phosra.com/api/v1/policies/c3d4e5f6-a7b8-9012-cdef-123456789012/rules \
  -H "Authorization: Bearer <access_token>"
Responsejson
[
  {
    "id": "d4e5f6a7-b8c9-0123-def0-123456789abc",
    "policy_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "category": "web_filtering",
    "enabled": true,
    "config": {
      "block_categories": [
        "adult",
        "gambling",
        "violence"
      ]
    },
    "created_at": "2025-01-10T09:05:00Z"
  }
]
POST/policies/{policyID}/rules

Add a rule to a policy. The category must be one of the 104 supported categories (see GET /rule-categories). Config schema varies per category (see Category Reference).

Request fields

category

Rule category (e.g. web_filtering, screen_time, app_restrictions)

stringrequired
enabled

Whether the rule is active (default: true)

boolean
config

Category-specific configuration object

objectrequired

Response fields

id

Rule identifier

uuid
policy_id

Parent policy identifier

uuid
category

One of 104 rule categories (e.g. web_filtering, screen_time, ai_chatbot_tier_gate). See GET /rule-categories.

string
enabled

Whether this rule is active

boolean
config

Category-specific configuration (JSONB)

object
created_at

Rule creation timestamp

datetime
Requestcurl
curl -X POST https://api.phosra.com/api/v1/policies/c3d4e5f6-a7b8-9012-cdef-123456789012/rules \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "screen_time",
    "enabled": true,
    "config": {
      "daily_limit_minutes": 120,
      "bedtime": "21:00",
      "wake_time": "07:00"
    }
  }'
Responsejson
{
  "id": "f6a7b8c9-d0e1-2345-f012-3456789abcde",
  "policy_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "category": "screen_time",
  "enabled": true,
  "config": {
    "daily_limit_minutes": 120,
    "bedtime": "21:00",
    "wake_time": "07:00"
  },
  "created_at": "2025-01-10T09:10:00Z"
}
PUT/rules/{ruleID}

Update an existing policy rule's configuration or enabled status. The category cannot be changed — delete and recreate if a different category is needed.

Request fields

enabled

Whether the rule is active

boolean
config

Updated category-specific configuration

object

Response fields

id

Rule identifier

uuid
policy_id

Parent policy identifier

uuid
category

One of 104 rule categories (e.g. web_filtering, screen_time, ai_chatbot_tier_gate). See GET /rule-categories.

string
enabled

Whether this rule is active

boolean
config

Category-specific configuration (JSONB)

object
created_at

Rule creation timestamp

datetime
Requestcurl
curl -X PUT https://api.phosra.com/api/v1/rules/d4e5f6a7-b8c9-0123-def0-123456789abc \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "config": { "daily_limit_minutes": 90, "bedtime": "20:00" }
  }'
Responsejson
{
  "id": "d4e5f6a7-b8c9-0123-def0-123456789abc",
  "policy_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "category": "time_daily_limit",
  "enabled": true,
  "config": {
    "daily_limit_minutes": 90,
    "bedtime": "20:00"
  },
  "created_at": "2025-01-10T09:05:00Z"
}
DELETE/rules/{ruleID}

Remove a rule from a policy. The rule is permanently deleted. To temporarily disable a rule, set enabled to false instead.

Requestcurl
curl -X DELETE https://api.phosra.com/api/v1/rules/d4e5f6a7-b8c9-0123-def0-123456789abc \
  -H "Authorization: Bearer <access_token>"
Responsejson
// 204 No Content
PUT/policies/{policyID}/rules/bulk

Create or update multiple rules in a single request. For each entry, if a rule with the given category already exists on the policy it is updated; otherwise a new rule is created. This is the recommended way to configure multiple categories at once.

Request fields

rules

Array of rule objects with category, enabled, and config

object[]required

Response fields

created

Number of new rules created

integer
updated

Number of existing rules updated

integer
Requestcurl
curl -X PUT https://api.phosra.com/api/v1/policies/c3d4e5f6-a7b8-9012-cdef-123456789012/rules/bulk \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      { "category": "web_filter_level", "config": { "level": "strict" } },
      { "category": "time_daily_limit", "config": { "daily_limit_minutes": 120 } },
      { "category": "content_rating", "config": { "max_mpaa": "PG", "max_esrb": "E" } }
    ]
  }'
Responsejson
{
  "created": 1,
  "updated": 2
}
GET/rule-categories

List all 104 supported rule categories grouped by domain. Includes the original 47 baseline categories and the 57 CSM-aligned expansion categories (age assurance, AI safety, CSM content + privacy ratings, algorithmic/social, platform accountability, time, and school/literacy). Each entry returns its slug, human label, group, and the laws that reference it. This endpoint is public.

Response fields

total

Total number of supported rule categories (currently 104)

integer
groups

Domain groups (content, time, purchase, social, web, privacy, monitoring, algorithmic_safety, notifications, advertising_data, access_control, age_assurance, ai_safety, csm_content, csm_privacy, platform_accountability, school_literacy)

object[]
categories

All category definitions

object[]
Requestcurl
curl https://api.phosra.com/api/v1/rule-categories
Responsejson
{
  "total": 104,
  "groups": [
    {
      "key": "age_assurance",
      "label": "Age Assurance",
      "categories": [
        "os_age_signal_ingest",
        "age_signal_broadcast",
        "parental_attestation_cert",
        "hard_id_verification_escalation",
        "app_store_age_attestation"
      ]
    },
    {
      "key": "ai_safety",
      "label": "AI Safety",
      "categories": [
        "ai_chatbot_tier_gate",
        "ai_product_classification_gate",
        "ai_dim_keep_kids_safe_threshold",
        "ai_dim_data_responsibility_threshold",
        "ai_dim_transparency_threshold",
        "ai_no_simulated_companionship",
        "ai_no_unsupervised_therapy",
        "ai_no_self_harm_promotion",
        "ai_no_csam_generation",
        "ai_no_personhood_deception",
        "ai_no_engagement_dark_patterns",
        "ai_is_it_real_disclosure",
        "ai_chatbot_age_assertion",
        "ai_companion_block",
        "ai_toy_safety_cert",
        "ai_training_data_opt_out"
      ]
    },
    {
      "key": "csm_content",
      "label": "Content (CSM 10-dim)",
      "categories": [
        "csm_age_gate",
        "violence_threshold",
        "firearm_content_block",
        "sexual_content_threshold",
        "profanity_threshold",
        "commercial_pressure_threshold",
        "substance_content_threshold",
        "prosocial_weight",
        "role_model_weight",
        "representation_weight",
        "educational_credit",
        "nfk_hard_block",
        "csm_seal_allowlist"
      ]
    },
    {
      "key": "csm_privacy",
      "label": "Privacy (CSM)",
      "categories": [
        "csm_privacy_tier_gate",
        "csm_privacy_score_threshold",
        "csm_privacy_dimension_gate",
        "csm_privacy_seal_required",
        "csm_privacy_unrated_default",
        "data_minimization_enforce",
        "third_party_tracker_block",
        "minor_data_sale_audit_log",
        "geolocation_precision_cap",
        "dpia_request_generator"
      ]
    },
    {
      "key": "algorithmic_safety",
      "label": "Algo / Social",
      "categories": [
        "infinite_scroll_block",
        "autoplay_disable",
        "stranger_dm_block",
        "stranger_outreach_friction"
      ]
    },
    {
      "key": "platform_accountability",
      "label": "Platform Accountability",
      "categories": [
        "social_media_warning_label_render",
        "gambling_mechanics_block",
        "platform_liability_evidence_capture",
        "streaming_age_rating_enforce",
        "teen_minimum_age_16_gate"
      ]
    },
    {
      "key": "time",
      "label": "Time",
      "categories": [
        "phone_free_school_hours"
      ]
    },
    {
      "key": "school_literacy",
      "label": "School / Literacy",
      "categories": [
        "student_privacy_school_mode",
        "digital_literacy_curriculum_link",
        "esafety_commission_reporting"
      ]
    }
  ],
  "categories": [
    {
      "name": "ai_chatbot_tier_gate",
      "group": "ai_safety",
      "description": "Gate chatbot access by Common Sense AI rating tier",
      "laws": [
        "Common Sense AI Ratings",
        "NY S9051",
        "CA SB 243"
      ]
    },
    {
      "name": "os_age_signal_ingest",
      "group": "age_assurance",
      "description": "Consume OS-level age signals published by the device",
      "laws": [
        "CA AB 1043",
        "UT App Store Accountability Act"
      ]
    },
    {
      "name": "phone_free_school_hours",
      "group": "time",
      "description": "Block minor-targeted apps during school hours via a bell-schedule profile",
      "laws": [
        "CA AB 3216",
        "FL HB 379",
        "IN HB 1284",
        "NYC Smartphone-Free Schools"
      ]
    }
  ]
}

3.1 104 Mandatory Policy Categories

PCSS v1.0 defines 104 policy categories across 19 domains. The 76 legislation- and CSM-driven categories (including the 57 Common Sense Media / age-assurance / AI-safety expansions) are backed by specific child safety laws and MUST be enforced by all compliant platforms.

algo_feed_control

Control algorithmic feed recommendations; enforce chronological mode for minors

KOSAKOSMACA SB 976EU DSA
addictive_design_control

Disable infinite scroll, autoplay, streaks, like counts, and daily rewards

KOSACT SB 3EU DSAUK OSA
notification_curfew

Suppress notifications during defined quiet hours (e.g., 20:00-07:00)

VA SB 854NY SAFE for Kids
usage_timer_notification

Periodic usage reminders at configurable intervals (15/30/45/60 min)

MN HF 2TN HB 1891
targeted_ad_block

Block all targeted/behavioral advertising for minors

COPPA 2.0EU DSAIndia DPDPA
dm_restriction

Restrict direct messaging: none, contacts_only, or everyone

CT SB 3UK OSA
age_gate

Require age verification before platform access

KOSMAFL HB 3Australia Online Safety Act
data_deletion_request

Enable one-click data deletion request for child accounts

COPPA 2.0NY NYCDPA
geolocation_opt_in

Default geolocation sharing to off; require explicit opt-in

CT SB 3MD Kids CodeCOPPA update
csam_reporting

Ensure CSAM detection/reporting mechanisms are enabled on platforms

CIPAEARN IT ActUK OSACanada C-63
library_filter_compliance

CIPA E-rate filtering for schools and libraries

CIPA
ai_minor_interaction

Restrict AI systems that exploit or manipulate children

EU AI Act
social_media_min_age

Enforce hard minimum age ban for social media access

AU SMMAUT SMRA
image_rights_minor

Protect minors' image rights; restrict unauthorized sharing

France SREN
parental_consent_gate

Require verifiable parental consent before account creation or data collection

COPPAKOSMAGDPR Art. 8India DPDPA15+ state laws
parental_event_notification

Notify parents when minors create accounts or encounter flagged content

LA Act 456OH HB 33
screen_time_report

Generate and deliver screen time usage reports to parents

VA SB 854TN HB 1891MN HF 2
commercial_data_ban

Ban commercial sale, sharing, or profiling of minor data

NY NYCDPACOPPA 2.0India DPDPABR LGPD
algorithmic_audit

Require algorithmic transparency reports and independent audits

KOSAEU DSAEU AI ActUK OSA
os_age_signal_ingest

Consume OS-level age signals published by the device (iOS/Android) and attach them to the active policy context

CA AB 1043UT App Store Accountability Act
age_signal_broadcast

Broadcast an authenticated age band to downstream apps and platforms so they can gate content without re-verifying

CA AB 1043EU DSAUK OSA
parental_attestation_cert

Issue a signed parental-attestation certificate that platforms accept as proof of consent and age

COPPA 2.0KOSMALA Act 456
hard_id_verification_escalation

Escalate to hard ID verification (document or biometric) when soft signals are insufficient or contested

UK OSAFL HB 3LA HB 142
app_store_age_attestation

Require app stores to pass an attested age band at install/purchase time before minor-targeted apps may run

UT App Store Accountability ActTX SB 2420
ai_chatbot_tier_gate

Gate chatbot access by Common Sense AI rating tier (green / yellow / red) aligned to the child's age band

Common Sense AI RatingsNY S9051CA SB 243
ai_product_classification_gate

Gate the whole AI product based on its CSM classification (general, companion, therapy, tutoring, etc.)

Common Sense AI RatingsEU AI Act
ai_dim_keep_kids_safe_threshold

Require AI products to meet the CSM 'Keep Kids Safe' dimension score threshold for the child's age

Common Sense AI Ratings
ai_dim_data_responsibility_threshold

Require AI products to meet the CSM 'Data Responsibility' dimension threshold

Common Sense AI RatingsCOPPA 2.0
ai_dim_transparency_threshold

Require AI products to meet the CSM 'Transparency & Accountability' dimension threshold

Common Sense AI RatingsEU AI Act
ai_no_simulated_companionship

Block AI features that simulate romantic, sexual, or companionship relationships with minors

NY S9051CA SB 243
ai_no_unsupervised_therapy

Block AI that provides unsupervised therapy or mental-health counseling to minors

NY S9051IL HB 4472
ai_no_self_harm_promotion

Block AI outputs that promote, instruct, or glamorize self-harm, suicide, or eating disorders

NY S9051KOSAUK OSA
ai_no_csam_generation

Block generative AI from producing CSAM or sexualized minor content; require provider-side safeguards

NY S9051EARN IT ActEU AI Act
ai_no_personhood_deception

Prohibit AI from asserting it is a human, licensed professional, or trusted adult to minors

NY S9051CA SB 243
ai_no_engagement_dark_patterns

Prohibit AI systems from using engagement dark patterns (streaks, guilt prompts, infinite sessions) on minors

NY S9051EU AI ActFTC UDAP
ai_is_it_real_disclosure

Require clear, age-appropriate 'is it real?' disclosure whenever minors interact with AI-generated content or avatars

NY S9051EU AI Act
ai_chatbot_age_assertion

Chatbots MUST declare minor-safety mode on every session and refuse to downgrade when challenged

NY S9051CA SB 243
ai_companion_block

Block AI companion apps (Replika-class) for under-18 users by default

NY S9051CA SB 243IL HB 4472
ai_toy_safety_cert

Require CSM or equivalent safety certification for connected / AI-enabled toys

Common Sense AI RatingsCPSC guidance
ai_training_data_opt_out

Default minors' data and content out of AI training sets; provide verifiable opt-out for parents

COPPA 2.0EU AI ActCA CCPA
csm_age_gate

Use the Common Sense Media recommended age as the primary age gate for a title

Common Sense Media Ratings
violence_threshold

Enforce a maximum score on the CSM violence dimension

Common Sense Media RatingsKOSA
firearm_content_block

Block content with firearm depictions above the age-appropriate CSM threshold

Common Sense Media Ratings
sexual_content_threshold

Enforce a maximum score on the CSM sexual content dimension

Common Sense Media RatingsUK OSA
profanity_threshold

Enforce a maximum score on the CSM language / profanity dimension

Common Sense Media Ratings
commercial_pressure_threshold

Enforce a maximum score on the CSM consumerism / commercial pressure dimension

Common Sense Media RatingsFTC endorsement guides
substance_content_threshold

Enforce a maximum score on the CSM drinking, drugs & smoking dimension

Common Sense Media Ratings
prosocial_weight

Boost titles that score high on the CSM positive messages dimension

Common Sense Media Ratings
role_model_weight

Boost titles that score high on the CSM positive role models dimension

Common Sense Media Ratings
representation_weight

Boost titles that score high on the CSM diverse representations dimension

Common Sense Media Ratings
educational_credit

Credit screen time spent on CSM-tagged educational titles against the child's daily cap

Common Sense Media Ratings
nfk_hard_block

Hard-block titles marked 'Not for Kids' regardless of other settings

Common Sense Media Ratings
csm_seal_allowlist

Allow only titles carrying the Common Sense Seal when strict mode is enabled

Common Sense Media Ratings
csm_privacy_tier_gate

Gate products by CSM privacy tier (warning / caution / pass)

CSM Privacy RatingsCOPPACA CCPA
csm_privacy_score_threshold

Require a minimum CSM privacy score (0-100) before a product is usable by a minor

CSM Privacy RatingsCOPPA 2.0
csm_privacy_dimension_gate

Gate per-dimension within the CSM privacy rubric (e.g., data-sale, third-party sharing, retention)

CSM Privacy RatingsEU GDPR
csm_privacy_seal_required

Require the CSM Privacy Seal before installing or activating a minor-facing product

CSM Privacy Ratings
csm_privacy_unrated_default

Default policy for unrated products: block, warn, or allow with telemetry off

CSM Privacy RatingsCOPPA
data_minimization_enforce

Enforce strict data-minimization at collection; reject non-essential fields for minor accounts

COPPA 2.0EU GDPRCA CCPAIndia DPDPA
third_party_tracker_block

Block third-party trackers, SDKs, and ad networks inside minor sessions

COPPA 2.0EU GDPRCA CCPA
minor_data_sale_audit_log

Require an immutable audit log of any data access, sharing, or sale involving a minor

NY NYCDPACA CCPACOPPA 2.0
geolocation_precision_cap

Cap geolocation precision (e.g., city-level max) for minor accounts

CT SB 3MD Kids CodeCOPPA
dpia_request_generator

Generate a Data Protection Impact Assessment (DPIA) request packet for a product on demand

UK Age-Appropriate Design CodeEU GDPR Art. 35
infinite_scroll_block

Hard-disable infinite scroll / auto-loading feeds for minor accounts

KOSACT SB 3NY SAFE for Kids
autoplay_disable

Hard-disable autoplay of the next video or episode for minor accounts

KOSACA SB 976NY SAFE for Kids
stranger_dm_block

Block DMs from accounts not already connected to the minor

CT SB 3UK OSAKOSA
stranger_outreach_friction

Add friction (challenge / cooldown / parental alert) when strangers attempt to contact a minor

CT SB 3UK OSAKOSA
social_media_warning_label_render

Render the Surgeon-General-style social media warning label on entry to minor sessions

CA AB 56NY A 8365Surgeon General 2024 Advisory
gambling_mechanics_block

Block loot boxes, wagering mechanics, and gambling-adjacent monetization for minors

EU DSAUK OSAFTC guidanceBE Gaming Commission
platform_liability_evidence_capture

Capture hashed evidence packets (design decisions, A/B tests) usable in duty-of-care litigation

KOSAUK OSACA AADC
streaming_age_rating_enforce

Enforce platform-declared streaming age ratings on playback; refuse titles above the child's band

Common Sense Media RatingsEU AVMSD
teen_minimum_age_16_gate

Enforce a minimum-age-16 gate on social media accounts where required by jurisdiction

AU SMMAFL HB 3UT SMRA
phone_free_school_hours

Block minor-targeted social / entertainment apps during school hours via a bell-schedule profile

CA AB 3216FL HB 379IN HB 1284NYC Smartphone-Free Schools
student_privacy_school_mode

Switch a device to school-mode: scoped telemetry, education-only apps, FERPA-safe data flows

FERPASOPIPACIPANY Education Law 2-d
digital_literacy_curriculum_link

Link a minor's account to a CSM / state-approved digital-literacy curriculum and track completion

CA AB 873FL HB 379Common Sense Education
esafety_commission_reporting

Emit eSafety Commission-compliant reports on complaints, takedowns, and minor-harm incidents

AU Online Safety ActUK OSAEU DSA

See the complete API reference below for full JSON schemas, field constraints, age-based defaults, platform support, and code examples for all 104 categories.

4. Regulated Platforms

All technology platforms serving minors SHALL register with the Phosra platform registry. Each platform declares its category, compliance level, supported capabilities, and authentication mechanism.

GET/providers

List all available providers with their integration tier, supported capabilities, and authentication method. This endpoint is public and does not require authentication.

Response fields

[]

Array of provider objects

Provider[]
Requestcurl
curl https://api.phosra.com/api/v1/providers
Responsejson
[
  {
    "id": "nextdns",
    "name": "NextDNS",
    "category": "dns",
    "tier": "live",
    "description": "DNS-level web filtering and analytics",
    "auth_type": "api_key",
    "capabilities": [
      "web_filtering",
      "safe_search",
      "youtube_restricted",
      "block_bypass_methods"
    ]
  },
  {
    "id": "cleanbrowing",
    "name": "CleanBrowsing",
    "category": "dns",
    "tier": "live",
    "description": "Family-friendly DNS filtering",
    "auth_type": "api_key",
    "capabilities": [
      "web_filtering",
      "safe_search"
    ]
  }
]
GET/platforms/{platformID}

Get detailed information about a specific provider including capabilities, authentication method, and integration tier. This endpoint is public.

Response fields

id

Provider slug (e.g. nextdns, cleanbrowing)

string
name

Provider display name

string
category

One of: dns, streaming, gaming, device, browser

enum
tier

Integration level: live, partial, or stub

enum
description

Human-readable provider description

string
auth_type

One of: api_key, oauth2, manual

enum
capabilities

Supported rule categories for this provider

string[]
Requestcurl
curl https://api.phosra.com/api/v1/platforms/nextdns
Responsejson
{
  "id": "nextdns",
  "name": "NextDNS",
  "category": "dns",
  "tier": "live",
  "description": "DNS-level web filtering and analytics",
  "auth_type": "api_key",
  "capabilities": [
    "web_filtering",
    "safe_search",
    "youtube_restricted",
    "block_bypass_methods"
  ]
}
GET/platforms/by-category

Filter platforms by category (dns, streaming, gaming, device, browser). Useful for discovering which platforms serve a particular need. Query parameter: ?category=dns

Request fields

category

Platform category filter (query parameter)

stringrequired
Requestcurl
curl "https://api.phosra.com/api/v1/platforms/by-category?category=dns"
Responsejson
[
  {
    "id": "nextdns",
    "name": "NextDNS",
    "tier": "live"
  },
  {
    "id": "cleanbrowsing",
    "name": "CleanBrowsing",
    "tier": "live"
  }
]
GET/platforms/by-capability

Filter platforms by supported rule category. Returns all platforms that can enforce a specific rule type. Query parameter: ?capability=web_filter_level

Request fields

capability

Rule category to filter by (query parameter)

stringrequired
Requestcurl
curl "https://api.phosra.com/api/v1/platforms/by-capability?capability=web_filter_level"
Responsejson
[
  {
    "id": "nextdns",
    "name": "NextDNS",
    "tier": "live",
    "support": "full"
  },
  {
    "id": "cleanbrowsing",
    "name": "CleanBrowsing",
    "tier": "live",
    "support": "partial"
  }
]
COMPLIANT

Full API enforcement. Real-time policy push.

  • NextDNS
  • CleanBrowsing
  • Android / Google Family Link
PROVISIONAL

Limited API. Partial enforcement capability.

  • Microsoft Family Safety
  • Apple Screen Time (MDM)
PENDING COMPLIANCE

No API. Manual compliance instructions provided.

  • Netflix, Disney+, Prime Video, YouTube
  • Hulu, Max, Roku
  • Xbox, PlayStation, Nintendo

5. Compliance Verification

Platforms MUST establish a compliance link to prove they can receive enforcement instructions. Credentials are encrypted with AES-256-GCM at rest. Platforms SHALL support periodic re-verification.

Credential Security: All platform credentials MUST be encrypted using AES-256-GCM before storage. Plaintext credentials MUST NOT be logged or stored unencrypted at any point in the pipeline.

POST/connections

Establish a connection between a family and a provider. Credentials are encrypted with AES-256-GCM before storage. The connection is verified immediately upon creation.

Request fields

family_id

Family to connect the provider to

uuidrequired
provider_id

Provider slug (e.g. nextdns, android)

stringrequired
credentials

Provider-specific credentials (API key, OAuth token, etc.)

stringrequired

Response fields

id

Connection identifier

uuid
family_id

Owning family identifier

uuid
provider_id

Connected provider slug

string
status

One of: connected, disconnected, error

enum
last_sync_at

Last successful sync timestamp

datetime
last_sync_status

Status of last sync attempt

string
connected_at

Initial connection timestamp

datetime
Requestcurl
curl -X POST https://api.phosra.com/api/v1/connections \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "family_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "provider_id": "nextdns",
    "credentials": "your-nextdns-api-key"
  }'
Responsejson
{
  "id": "e5f6a7b8-c9d0-1234-ef01-23456789abcd",
  "family_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider_id": "nextdns",
  "status": "connected",
  "last_sync_at": null,
  "last_sync_status": null,
  "connected_at": "2025-01-10T10:00:00Z"
}

5.2 Quick Setup API

The Quick Setup API provides a single-call onboarding flow that creates a family (if needed), registers a child, generates all 104 age-appropriate policy rules, and activates the policy. This endpoint SHOULD be the primary entry point for parent-facing applications.

Endpoint

POST /setup/quick

Request Body

{
  "family_id": "uuid (optional — omit to create new family)",
  "family_name": "string (optional — used when creating new family)",
  "child_name": "string (required)",
  "birth_date": "YYYY-MM-DD (required)",
  "strictness": "recommended | strict | relaxed"
}

Response

{
  "family": { "id": "...", "name": "..." },
  "child": { "id": "...", "name": "Emma", "birth_date": "2019-03-15" },
  "policy": { "id": "...", "status": "active" },
  "rules": [ ... ],  // ~20-25 enabled rules
  "age_group": "child",
  "max_ratings": { "mpaa": "PG", "tv": "TV-Y7", "esrb": "E" },
  "rule_summary": {
    "screen_time_minutes": 90,
    "bedtime_hour": 20,
    "web_filter_level": "strict",
    "content_rating": "PG",
    "total_rules_enabled": 22
  }
}

Strictness levels: recommended uses age-appropriate defaults. strict reduces screen time by 30% and tightens timer intervals.relaxed increases screen time by 30% and extends timer intervals.

POST/setup/quick

Single-call onboarding that creates a family (if needed), registers a child, generates all 45 age-appropriate policy rules, and activates the policy. This is the recommended entry point for parent-facing applications.

Request fields

family_id

Existing family ID (optional — omit to create new family)

uuid
family_name

Family name (used when creating new family)

string
child_name

Child display name

stringrequired
birth_date

Child date of birth (YYYY-MM-DD)

daterequired
strictness

One of: recommended (default), strict, relaxed

enum

Response fields

family

Created or existing family

object
child

Created child profile with computed age

object
policy

Active policy with rule count

object
rules

Generated policy rules (~20-25 enabled)

object[]
age_group

Computed age group (toddler, child, tween, teen)

string
max_ratings

Age-appropriate content ratings across 5 systems

object
Requestcurl
curl -X POST https://api.phosra.com/api/v1/setup/quick \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "child_name": "Emma",
    "birth_date": "2019-03-15",
    "strictness": "recommended"
  }'
Responsejson
{
  "family": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Family"
  },
  "child": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Emma",
    "birth_date": "2019-03-15",
    "age": 6
  },
  "policy": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "status": "active",
    "rules_count": 22
  },
  "age_group": "child",
  "max_ratings": {
    "mpaa": "PG",
    "tv": "TV-Y7",
    "esrb": "E",
    "pegi": "7",
    "csm": "6+"
  }
}

6. Policy Enforcement

The Phosra Enforcement Engine fans out policy rules to all verified platforms concurrently. Platforms MUST accept enforcement requests and report per-rule results. Enforcement jobs track status as: pending →running →completed / partial / failed.

Enforcement flow: Trigger enforcement → Job created → Fan out to platforms → Collect per-provider results → Retry failures

POST/children/{childID}/enforce

Push the child's active policy rules to all verified compliance links (platform connections). Creates an enforcement job that fans out to each connected platform concurrently. Returns the job for status polling.

Response fields

id

Sync job identifier

uuid
child_id

Target child identifier

uuid
policy_id

Policy being enforced

uuid
trigger_type

One of: manual, auto, webhook

enum
status

One of: pending, running, completed, failed, partial

enum
started_at

Job start timestamp

datetime
completed_at

Job completion timestamp

datetime
created_at

Job creation timestamp

datetime
Requestcurl
curl -X POST https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901/enforce \
  -H "Authorization: Bearer <access_token>"
Responsejson
{
  "id": "f6a7b8c9-d0e1-2345-f012-3456789abcde",
  "child_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "trigger_type": "manual",
  "status": "pending",
  "created_at": "2025-01-10T10:30:00Z"
}
GET/children/{childID}/enforcement/jobs

List all enforcement jobs for a child, ordered by creation time (newest first). Useful for viewing enforcement history and identifying failures.

Response fields

[]

Array of enforcement job objects

EnforcementJob[]
Requestcurl
curl https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901/enforcement/jobs \
  -H "Authorization: Bearer <access_token>"
Responsejson
[
  {
    "id": "f6a7b8c9-d0e1-2345-f012-3456789abcde",
    "child_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "trigger_type": "manual",
    "status": "completed",
    "started_at": "2025-01-10T10:30:01Z",
    "completed_at": "2025-01-10T10:30:05Z",
    "created_at": "2025-01-10T10:30:00Z"
  }
]
POST/children/{childID}/sync

Trigger enforcement sync for a child across all connected providers. Pushes the active policy's rules to each provider. Returns a sync job that can be polled for status.

Response fields

id

Sync job identifier

uuid
child_id

Target child identifier

uuid
policy_id

Policy being enforced

uuid
trigger_type

One of: manual, auto, webhook

enum
status

One of: pending, running, completed, failed, partial

enum
started_at

Job start timestamp

datetime
completed_at

Job completion timestamp

datetime
created_at

Job creation timestamp

datetime
Requestcurl
curl -X POST https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901/sync \
  -H "Authorization: Bearer <access_token>"
Responsejson
{
  "id": "f6a7b8c9-d0e1-2345-f012-3456789abcde",
  "child_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "policy_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "trigger_type": "manual",
  "status": "pending",
  "started_at": null,
  "completed_at": null,
  "created_at": "2025-01-10T10:30:00Z"
}
GET/sync/jobs/{jobID}

Check the status of a sync job. Poll this endpoint until status is completed, failed, or partial.

Response fields

id

Sync job identifier

uuid
child_id

Target child identifier

uuid
policy_id

Policy being enforced

uuid
trigger_type

One of: manual, auto, webhook

enum
status

One of: pending, running, completed, failed, partial

enum
started_at

Job start timestamp

datetime
completed_at

Job completion timestamp

datetime
created_at

Job creation timestamp

datetime
Requestcurl
curl https://api.phosra.com/api/v1/sync/jobs/f6a7b8c9-d0e1-2345-f012-3456789abcde \
  -H "Authorization: Bearer <access_token>"
Responsejson
{
  "id": "f6a7b8c9-d0e1-2345-f012-3456789abcde",
  "child_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "policy_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "trigger_type": "manual",
  "status": "completed",
  "started_at": "2025-01-10T10:30:01Z",
  "completed_at": "2025-01-10T10:30:05Z",
  "created_at": "2025-01-10T10:30:00Z"
}
GET/sync/jobs/{jobID}/results

Get per-provider results for a completed sync job. Each result shows how many rules were applied, skipped, or failed for that provider.

Response fields

[]

Per-provider result breakdown

SyncJobResult[]
Requestcurl
curl https://api.phosra.com/api/v1/sync/jobs/f6a7b8c9-d0e1-2345-f012-3456789abcde/results \
  -H "Authorization: Bearer <access_token>"
Responsejson
[
  {
    "id": "a7b8c9d0-e1f2-3456-0123-456789abcdef",
    "sync_job_id": "f6a7b8c9-d0e1-2345-f012-3456789abcde",
    "provider_id": "nextdns",
    "status": "completed",
    "rules_applied": 8,
    "rules_skipped": 2,
    "rules_failed": 0,
    "error_message": null,
    "details": {
      "profile_id": "abc123"
    }
  }
]
POST/enforcement/jobs/{jobID}/retry

Retry a failed or partial enforcement job. Only failed providers are retried — providers that previously succeeded are skipped. Requires the original job to be in failed or partial status.

Requestcurl
curl -X POST https://api.phosra.com/api/v1/enforcement/jobs/f6a7b8c9-d0e1-2345-f012-3456789abcde/retry \
  -H "Authorization: Bearer <access_token>"
Responsejson
{
  "id": "a1b2c3d4-new-retry-job-id",
  "parent_job_id": "f6a7b8c9-d0e1-2345-f012-3456789abcde",
  "status": "pending",
  "retry_count": 1,
  "providers_retrying": [
    "nextdns"
  ],
  "created_at": "2025-01-10T10:35:00Z"
}

7. Content Rating Standard

PCSS defines a unified content rating framework spanning 5 international rating systems. Platforms MUST map their internal content ratings to the nearest PCSS equivalent. Cross-system equivalences SHALL be computed with a confidence score (0-1).

GET/ratings/systems

List all supported content rating systems (MPAA, TV Parental Guidelines, ESRB, PEGI, Common Sense Media). This endpoint is public.

Response fields

[]

Array of rating system objects

RatingSystem[]
Requestcurl
curl https://api.phosra.com/api/v1/ratings/systems
Responsejson
[
  {
    "id": "mpaa",
    "name": "MPAA",
    "country": "US",
    "media_type": "film"
  },
  {
    "id": "tv",
    "name": "TV Parental Guidelines",
    "country": "US",
    "media_type": "tv"
  },
  {
    "id": "esrb",
    "name": "ESRB",
    "country": "US/CA",
    "media_type": "game"
  },
  {
    "id": "pegi",
    "name": "PEGI",
    "country": "EU",
    "media_type": "game"
  },
  {
    "id": "csm",
    "name": "Common Sense Media",
    "country": "US",
    "media_type": "general"
  }
]
GET/ratings/by-age

Look up the maximum appropriate content rating for a given age across all rating systems. This endpoint is public and useful for previewing age mappings without creating a child profile.

Request fields

age

Age in years (query parameter: ?age=10)

integerrequired

Response fields

age

Queried age

integer
ratings

Map of rating system ID to maximum allowed rating

object
Requestcurl
curl "https://api.phosra.com/api/v1/ratings/by-age?age=10"
Responsejson
{
  "age": 10,
  "ratings": {
    "mpaa": {
      "code": "PG",
      "name": "Parental Guidance Suggested",
      "min_age": 8
    },
    "tv": {
      "code": "TV-PG",
      "name": "Parental Guidance Suggested",
      "min_age": 8
    },
    "esrb": {
      "code": "E10+",
      "name": "Everyone 10+",
      "min_age": 10
    },
    "pegi": {
      "code": "PEGI 12",
      "name": "PEGI 12",
      "min_age": 12
    },
    "csm": {
      "code": "10+",
      "name": "Age 10+",
      "min_age": 10
    }
  }
}

8. Event Notifications

Platforms SHOULD register webhook endpoints to receive real-time enforcement notifications. All webhook payloads MUST be signed using HMAC-SHA256 with the webhook secret. Platforms MUST verify the X-Phosra-Signature header before processing.

# Signature verification
signature = HMAC-SHA256(webhook_secret, request_body)
# Compare with X-Phosra-Signature header (hex-encoded)

Supported events: enforcement.completed enforcement.failed policy.updated policy.activated compliance.verified compliance.failed

POST/webhooks

Register a webhook endpoint to receive real-time notifications for enforcement, policy, and compliance events. All payloads are signed with HMAC-SHA256 using the provided secret.

Request fields

url

HTTPS endpoint URL for delivery

stringrequired
events

Event types to subscribe to

string[]required
secret

HMAC-SHA256 signing secret

stringrequired

Response fields

id

Webhook identifier

string
family_id

Owning family identifier

uuid
url

Delivery endpoint URL

string
events

Subscribed event types

string[]
status

One of: active, paused, failed

enum
created_at

Webhook creation timestamp

datetime
Requestcurl
curl -X POST https://api.phosra.com/api/v1/webhooks \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/phosra",
    "events": ["enforcement.completed", "enforcement.failed", "policy.updated"],
    "secret": "whsec_your_secret_key"
  }'
Responsejson
{
  "id": "wh_abc123",
  "family_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://api.example.com/webhooks/phosra",
  "events": [
    "enforcement.completed",
    "enforcement.failed",
    "policy.updated"
  ],
  "status": "active",
  "created_at": "2025-01-10T10:00:00Z"
}
GET/webhooks/{webhookID}

Retrieve details of a specific webhook including its event subscriptions and delivery statistics.

Response fields

id

Webhook identifier

string
family_id

Owning family identifier

uuid
url

Delivery endpoint URL

string
events

Subscribed event types

string[]
status

One of: active, paused, failed

enum
created_at

Webhook creation timestamp

datetime
Requestcurl
curl https://api.phosra.com/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer <access_token>"
Responsejson
{
  "id": "wh_abc123",
  "family_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://api.example.com/webhooks/phosra",
  "events": [
    "enforcement.completed",
    "enforcement.failed",
    "policy.updated"
  ],
  "status": "active",
  "created_at": "2025-01-10T10:00:00Z"
}
PUT/webhooks/{webhookID}

Update a webhook's URL, event subscriptions, or secret. Changes take effect immediately for the next delivery.

Request fields

url

HTTPS endpoint URL for delivery

stringrequired
events

Event types to subscribe to

string[]required
secret

HMAC-SHA256 signing secret

stringrequired
Requestcurl
curl -X PUT https://api.phosra.com/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["enforcement.completed", "enforcement.failed", "policy.updated", "compliance.verified"]
  }'
Responsejson
// 200 OK
DELETE/webhooks/{webhookID}

Permanently delete a webhook. No further events will be delivered to this endpoint. Pending deliveries are cancelled.

Requestcurl
curl -X DELETE https://api.phosra.com/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer <access_token>"
Responsejson
// 204 No Content
POST/webhooks/{webhookID}/test

Send a test ping event to the webhook endpoint. Returns delivery status, response code, and latency. Use this to verify your endpoint is correctly configured and can handle HMAC signature verification.

Requestcurl
curl -X POST https://api.phosra.com/api/v1/webhooks/wh_abc123/test \
  -H "Authorization: Bearer <access_token>"
Responsejson
{
  "delivery_id": "del_test01",
  "event": "test.ping",
  "status": "delivered",
  "response_code": 200,
  "response_time_ms": 145
}
GET/webhooks/{webhookID}/deliveries

List recent webhook deliveries with status, response codes, and timestamps. Failed deliveries are retried with exponential backoff (1min, 5min, 30min). Delivery history is retained for 30 days.

Requestcurl
curl https://api.phosra.com/api/v1/webhooks/wh_abc123/deliveries \
  -H "Authorization: Bearer <access_token>"
Responsejson
[
  {
    "id": "del_001",
    "event": "enforcement.completed",
    "status": "delivered",
    "response_code": 200,
    "timestamp": "2025-01-12T18:05:00Z"
  },
  {
    "id": "del_002",
    "event": "policy.updated",
    "status": "delivered",
    "response_code": 200,
    "timestamp": "2025-01-12T17:30:00Z"
  }
]

9. Compliance Levels

Each platform is classified into one of three compliance levels. Platforms MUST progress toward full compliance. Regression from Compliant to a lower level SHALL trigger regulatory review.

COMPLIANT

Full API Enforcement

  • Platform MUST accept all enforcement requests via API
  • Platform MUST report per-rule enforcement results
  • Platform MUST support credential validation
  • Platform SHOULD support webhook notifications
PROVISIONAL

Limited API Access

  • Platform MUST provide at least read access to safety settings
  • Platform SHOULD accept write requests for supported capabilities
  • Platform MUST document unsupported enforcement categories
PENDING COMPLIANCE

Manual Compliance

  • Platform MUST provide documented safety configuration steps
  • Platform SHALL publish a public API roadmap within 12 months
  • Platform MUST NOT remain at Pending level beyond 24 months

10. Enforcement Timeline

The following timeline governs the transition to mandatory PCSS compliance for all regulated platforms.

Phase 1

Voluntary Adoption

Platforms MAY register and begin compliance integration. Early adopters receive Compliant certification.

Phase 2

Platform Registration

Platforms serving minors SHOULD register with the PCSS platform registry to track compliance status.

Phase 3

Full Enforcement

All platforms MUST achieve at least Provisional compliance. Platforms at Pending SHALL face regulatory review and potential enforcement action.

API Base URL

All PCSS API endpoints are served under:

https://phosra-api.fly.dev/api/v1

Platforms MUST use HTTPS in production environments. HTTP MAY be used only in development.

12. Parent Experience

Phosra provides a guided Quick Setup flow that enables parents to protect their children across all regulated platforms in under one minute. The three-step wizard handles family creation, age-based policy generation, and platform verification.

1

Tell Us About Your Child

Enter name, birth date, and choose a protection level (Recommended, Strict, or Relaxed).

2

Review Protections

See plain-language summary cards for screen time, content ratings, web filtering, social controls, privacy, and algorithm safety.

3

Connect Platforms

Verify compliance on platforms with a progress indicator. Enforce with one click after connecting.

What Gets Created

  • Family (if not already created)
  • Child profile with age computation
  • Active safety policy with ~20-25 enabled rules across all 104 categories
  • Age-appropriate content ratings across 5 rating systems
  • Legislation-compliant rules for algorithmic safety, notifications, advertising, and data privacy

13. Community Standards

Phosra supports community standards (also called movements) — curated rule sets based on expert guidance, research, and advocacy organizations. Parents MAY adopt one or more standards for each child to automatically generate matching policy rules.

Standards provide a "one-click" way to align with community guidelines like the Four Norms from Jonathan Haidt's Anxious Generation, Wait Until 8th, or Common Sense Media age ratings. When adopted, the standard's rules are merged into the child's active policy.

Expert Standards

Research-backed rule sets from child development experts and psychologists.

Community Pledges

Grassroots movements like Wait Until 8th and Smartphone Free Childhood.

Organization Guidelines

Recommendations from AAP, Common Sense Media, and other organizations.

Browse all available standards at /standards-library. The Phosra API currently includes 31 community standards spanning expert guidance, parenting pledges, and organizational recommendations.

GET/standards

List all available community standards (movements). Each standard defines a set of recommended rules based on expert guidance — e.g. Wait Until 8th, Four Norms (Anxious Generation), Common Sense Media guidelines. This endpoint is public.

Response fields

[]

Array of community standard objects

Standard[]
Requestcurl
curl https://api.phosra.com/api/v1/standards
Responsejson
[
  {
    "id": "four-norms",
    "slug": "four-norms",
    "name": "Four Norms (Anxious Generation)",
    "description": "Jonathan Haidt's four foundational norms for childhood in the smartphone age.",
    "rules_count": 6,
    "category": "expert"
  },
  {
    "id": "wait-until-8th",
    "slug": "wait-until-8th",
    "name": "Wait Until 8th",
    "description": "The pledge to wait until at least 8th grade before giving children a smartphone.",
    "rules_count": 4,
    "category": "pledge"
  }
]
GET/standards/{slug}

Get full details of a community standard including all recommended rules, age thresholds, and supporting research. This endpoint is public.

Response fields

id

Standard identifier

string
slug

URL-friendly slug

string
name

Standard display name

string
description

Summary of the standard's purpose

string
rules

Recommended rules with categories and values

object[]
rules_count

Number of rules in the standard

integer
category

Standard category (expert, pledge, organization)

string
Requestcurl
curl https://api.phosra.com/api/v1/standards/four-norms
Responsejson
{
  "id": "four-norms",
  "slug": "four-norms",
  "name": "Four Norms (Anxious Generation)",
  "description": "Jonathan Haidt's four foundational norms for childhood in the smartphone age.",
  "rules": [
    {
      "category": "social_media_min_age",
      "value": "16",
      "label": "No social media before 16"
    },
    {
      "category": "time_daily_limit",
      "value": "120",
      "label": "Phone-free schools"
    },
    {
      "category": "time_bedtime",
      "value": "enabled",
      "label": "Device-free bedrooms"
    }
  ],
  "rules_count": 6,
  "category": "expert"
}
GET/children/{childID}/standards

List all community standards adopted for a specific child. Adopted standards automatically generate corresponding policy rules.

Requestcurl
curl https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901/standards \
  -H "Authorization: Bearer <access_token>"
Responsejson
[
  {
    "standard_id": "four-norms",
    "name": "Four Norms (Anxious Generation)",
    "adopted_at": "2025-01-15T10:00:00Z",
    "rules_applied": 6
  }
]
POST/children/{childID}/standards

Adopt a community standard for a child. This generates policy rules matching the standard's recommendations and adds them to the child's active policy. If rules for the same categories already exist, they are updated to match the standard.

Request fields

standard_id

Slug of the community standard to adopt

stringrequired
Requestcurl
curl -X POST https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901/standards \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "standard_id": "four-norms" }'
Responsejson
{
  "standard_id": "four-norms",
  "name": "Four Norms (Anxious Generation)",
  "adopted_at": "2025-01-15T10:00:00Z",
  "rules_applied": 6,
  "rules_created": 3,
  "rules_updated": 3
}
DELETE/children/{childID}/standards/{standardID}

Remove a community standard from a child. The associated policy rules are not automatically deleted — they remain as manually-configured rules. To remove the rules as well, delete them individually or regenerate the policy from age.

Requestcurl
curl -X DELETE https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901/standards/four-norms \
  -H "Authorization: Bearer <access_token>"
Responsejson
// 204 No Content

14. Parental Control Sources

Phosra maintains a registry of 21 parental control applications and services that can be connected as sources — apps parents already use to manage their children's devices. Unlike target platforms that Phosra pushes rules to, sources are apps that Phosra integrates with to push rules through.

Public API

Direct API integration. Phosra pushes rules automatically via documented REST endpoints.

Qustodio, Apple Screen Time (MDM), Google Family Link

Managed API

Integration with platforms offering documented APIs. Phosra translates rules into each platform's native format.

Platforms with REST or MDM APIs

No API

Guided setup mode. Phosra generates step-by-step instructions for manual configuration.

Net Nanny, Norton Family, Kaspersky, Circle

Undocumented

Identified integration points. Availability may vary.

Bark Phone

Each source is mapped to Phosra's 104 rule categories with full, partial, or none support per capability. Browse all sources with their capability matrices at /parental-controls.

Source API Pattern

POST /v1/sources — Connect a parental control app to a child

POST /v1/sources/{sourceID}/sync — Push all rules to source

POST /v1/sources/{sourceID}/rules — Push individual capability

GET /v1/sources/{sourceID}/guide/{category} — Get guided setup steps (no-API sources)

15. Family Reports

The reporting API provides family-level overviews of enforcement status, compliance health, and per-child statistics. Reports SHOULD be used by parent-facing applications to surface the current protection state at a glance.

GET/families/{familyID}/reports/overview

Get a comprehensive overview report for a family including per-child enforcement status, compliance link health, recent activity, and rule coverage statistics.

Requestcurl
curl https://api.phosra.com/api/v1/families/a1b2c3d4-e5f6-7890-abcd-ef1234567890/reports/overview \
  -H "Authorization: Bearer <access_token>"
Responsejson
{
  "family_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "children": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Emma",
      "age": 6,
      "active_policy": "School Days",
      "rules_enabled": 22,
      "platforms_connected": 2,
      "last_enforcement": "2025-01-12T18:00:00Z",
      "enforcement_status": "healthy"
    }
  ],
  "compliance_summary": {
    "total_links": 2,
    "verified": 2,
    "failed": 0
  },
  "enforcement_summary": {
    "total_jobs_7d": 5,
    "success_rate": 1,
    "avg_rules_pushed": 26
  }
}

Feedback

Anonymous feedback endpoint for collecting user experience data. No authentication required.

POST/feedback

Submit product feedback or a feature request. This endpoint is public and does not require authentication, allowing anonymous feedback from site visitors.

Request fields

type

One of: bug, feature, general

enumrequired
message

Feedback message (max 2000 characters)

stringrequired
email

Optional contact email for follow-up

string
Requestcurl
curl -X POST https://api.phosra.com/api/v1/feedback \
  -H "Content-Type: application/json" \
  -d '{
    "type": "feature",
    "message": "Would love to see Roku integration",
    "email": "user@example.com"
  }'
Responsejson
{
  "id": "fb_abc123",
  "type": "feature",
  "message": "Would love to see Roku integration",
  "status": "new",
  "created_at": "2025-01-15T14:00:00Z"
}

Apple Device Sync

Native iOS integration endpoints for Apple Screen Time enforcement via FamilyControls, ManagedSettings, and DeviceActivity frameworks. Devices register with parent authorization, pull versioned policies with 304 Not Modified support, and report per-category enforcement results back to the API.

Device Registration

Parent-authenticated CRUD for managing child devices and capabilities

Policy Sync

Versioned policy pull with APNs silent push notifications on changes

Enforcement Reports

Per-category enforcement status reporting with framework context

APNs Silent Push Payload

When a policy is updated, Phosra sends a silent push notification to all active devices registered for that child. Your app MUST handle this in application(_:didReceiveRemoteNotification:fetchCompletionHandler:) and trigger a policy refresh via GET /device/policy.

Push Payload

{
  "aps": {
    "content-available": 1
  },
  "phosra": {
    "event": "policy.updated",
    "version": 3
  }
}

Fields

aps.content-availableAlways 1 — marks this as a silent/background push. No alert, sound, or badge.
phosra.eventEvent type. Currently always "policy.updated".
phosra.versionThe new policy version number. Compare with your cached version — if higher, call GET /device/policy.

APNs HTTP/2 Headers (Server → Apple)

apns-push-typebackground
apns-priority5 — required for silent push (priority 10 would require an alert)
apns-topicYour app's bundle ID (e.g. com.downtime.downtime)

Swift Handler Example

func application(
  _ application: UIApplication,
  didReceiveRemoteNotification userInfo: [AnyHashable: Any],
  fetchCompletionHandler handler: @escaping (UIBackgroundFetchResult) -> Void
) {
  guard let phosra = userInfo["phosra"] as? [String: Any],
        let event = phosra["event"] as? String,
        event == "policy.updated",
        let version = phosra["version"] as? Int else {
    handler(.noData)
    return
  }

  // Only refresh if the pushed version is newer than our cached version
  guard version > PolicyCache.shared.currentVersion else {
    handler(.noData)
    return
  }

  Task {
    do {
      let policy = try await PhosraAPI.fetchPolicy()
      PolicyEnforcer.shared.apply(policy)
      handler(.newData)
    } catch {
      handler(.failed)
    }
  }
}

Important

  • Enable Background Modes → Remote notifications in your Xcode project capabilities.
  • Silent push is best-effort — iOS may throttle or delay delivery. Always implement periodic polling as a fallback (recommended: every 15 minutes via BGAppRefreshTask).
  • The push is sent to all active devices for the child, not just the device that last polled.
  • If the device token changes (e.g. after app reinstall), update it via PUT /devices/{deviceID} with the new apns_token.
POST/children/{childID}/devices

Register an Apple device for on-device policy enforcement. Returns a one-time API key that the iOS app stores in Keychain. The API key is used for all subsequent device-auth requests (policy polling, reports, ack). The plaintext key is never stored server-side — only its SHA-256 hash.

Request fields

device_name

Human-readable name (e.g. 'Sofia\'s iPad')

stringrequired
device_model

Device model (e.g. 'iPad Pro 11-inch')

stringrequired
os_version

iOS version (e.g. '18.2')

stringrequired
app_version

Phosra app version (e.g. '1.0.0')

stringrequired
apns_token

Apple Push Notification token (optional)

string
capabilities

Apple frameworks the device supports (e.g. ['FamilyControls', 'ManagedSettings', 'DeviceActivity'])

string[]

Response fields

device

The registered device

DeviceRegistration
api_key

One-time device API key — store in Keychain immediately

string
Requestcurl
curl -X POST https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901/devices \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "device_name": "Sofia'\''s iPad",
    "device_model": "iPad Pro 11-inch",
    "os_version": "18.2",
    "app_version": "1.0.0"
  }'
Responsejson
{
  "device": {
    "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
    "child_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "family_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "platform_id": "apple",
    "device_name": "Sofia's iPad",
    "device_model": "iPad Pro 11-inch",
    "os_version": "18.2",
    "app_version": "1.0.0",
    "apns_token": null,
    "capabilities": [
      "FamilyControls",
      "ManagedSettings",
      "DeviceActivity"
    ],
    "enforcement_summary": {},
    "last_seen_at": null,
    "last_policy_version": 0,
    "status": "active",
    "created_at": "2026-02-17T10:00:00Z",
    "updated_at": "2026-02-17T10:00:00Z"
  },
  "api_key": "a3f8b2c1d4e5f6789012345678abcdef0123456789abcdef0123456789abcdef"
}
GET/children/{childID}/devices

List all registered Apple devices for a child. Shows each device's status, last seen time, and which policy version it last acknowledged. Useful for the parent dashboard to monitor device health.

Response fields

[]

Registered devices for this child

DeviceRegistration[]
Requestcurl
curl https://api.phosra.com/api/v1/children/b2c3d4e5-f6a7-8901-bcde-f12345678901/devices \
  -H "Authorization: Bearer <access_token>"
Responsejson
[
  {
    "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
    "child_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "family_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "platform_id": "apple",
    "device_name": "Sofia's iPad",
    "device_model": "iPad Pro 11-inch",
    "os_version": "18.2",
    "app_version": "1.0.0",
    "capabilities": [
      "FamilyControls",
      "ManagedSettings",
      "DeviceActivity"
    ],
    "enforcement_summary": {
      "content_rating": {
        "status": "enforced",
        "framework": "ManagedSettings"
      },
      "time_daily_limit": {
        "status": "enforced",
        "framework": "DeviceActivity"
      },
      "web_safesearch": {
        "status": "enforced",
        "framework": "ManagedSettings"
      }
    },
    "last_seen_at": "2026-02-17T14:30:00Z",
    "last_policy_version": 3,
    "status": "active",
    "created_at": "2026-02-17T10:00:00Z",
    "updated_at": "2026-02-17T14:30:00Z"
  }
]
PUT/devices/{deviceID}

Update device metadata such as APNs token, app version, or device name. All fields are optional — only provided fields are updated. Typically called when the iOS app updates or the APNs token rotates.

Request fields

device_name

Updated device name

string
apns_token

Updated Apple Push Notification token

string
app_version

Updated app version after upgrade

string
os_version

Updated iOS version after OS update

string

Response fields

id

Device registration identifier

uuid
child_id

Associated child identifier

uuid
family_id

Parent family identifier

uuid
platform_id

Platform slug (always 'apple')

string
device_name

Human-readable device name (e.g. 'Sofia\'s iPad')

string
device_model

Device model identifier (e.g. 'iPad Pro 11-inch')

string
os_version

iOS version (e.g. '18.2')

string
app_version

Phosra iOS app version (e.g. '1.0.0')

string
apns_token

Apple Push Notification token (optional)

string
capabilities

Apple frameworks the device supports (e.g. FamilyControls, ManagedSettings, DeviceActivity, WebContentFilter)

string[]
enforcement_summary

Per-category enforcement results from the device's last enforcement_status report

object
last_seen_at

Last time the device contacted the API

datetime
last_policy_version

Last policy version the device acknowledged

integer
status

One of: active, inactive, revoked

enum
created_at

Registration timestamp

datetime
updated_at

Last update timestamp

datetime
Requestcurl
curl -X PUT https://api.phosra.com/api/v1/devices/d1e2f3a4-b5c6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "apns_token": "new_apns_token_abc123",
    "app_version": "1.1.0"
  }'
Responsejson
{
  "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
  "child_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "platform_id": "apple",
  "device_name": "Sofia's iPad",
  "device_model": "iPad Pro 11-inch",
  "os_version": "18.2",
  "app_version": "1.1.0",
  "apns_token": "new_apns_token_abc123",
  "last_policy_version": 3,
  "status": "active",
  "updated_at": "2026-02-17T15:00:00Z"
}
DELETE/devices/{deviceID}

Revoke a device's API key, preventing it from polling for policies or submitting reports. The device registration is kept for audit purposes but marked as 'revoked'. The iOS app will receive 401 on its next request.

Requestcurl
curl -X DELETE https://api.phosra.com/api/v1/devices/d1e2f3a4-b5c6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <access_token>"
GET/device/policy

Fetch the compiled policy document for the authenticated device's child. Returns a structured JSON document the iOS app interprets to configure FamilyControls, ManagedSettings, and DeviceActivity. Supports conditional polling: pass ?since_version=N to get a 304 Not Modified if the policy hasn't changed. Auth: X-Device-Key header (not Bearer JWT).

Request fields

since_version

Return 304 if current version is <= this value (query parameter)

integer

Response fields

version

Policy version (auto-increments on changes)

integer
child_id

Child this policy applies to

uuid
child_age

Child's current age in years

integer
age_group

Age group label (e.g. 'Child', 'Teen')

string
policy_id

Source policy identifier

uuid
status

Policy status (active)

string
generated_at

When the compiled document was generated

datetime
content_filter

Content restriction settings

object
screen_time

Screen time limits

object
purchases

Purchase controls

object
privacy

Privacy settings

object
social

Social interaction controls

object
notifications

Notification controls

object
web_filter

Web filtering settings

object
Requestcurl
curl https://api.phosra.com/api/v1/device/policy?since_version=2 \
  -H "X-Device-Key: <device_api_key>"
Responsejson
{
  "version": 3,
  "child_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "child_age": 7,
  "age_group": "Child",
  "policy_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "active",
  "generated_at": "2026-02-17T15:00:00Z",
  "content_filter": {
    "age_rating": "4+",
    "max_ratings": {
      "mpaa": "PG",
      "tvpg": "TV-Y7",
      "esrb": "E",
      "pegi": "7",
      "csm": "7+",
      "apple": "4+"
    },
    "blocked_apps": [
      "com.epic.fortnite"
    ],
    "allowed_apps": [],
    "allowlist_mode": false
  },
  "screen_time": {
    "daily_limit_minutes": 120,
    "per_app_limits": [
      {
        "bundle_id": "com.google.youtube",
        "daily_minutes": 30
      }
    ],
    "downtime_windows": [
      {
        "days_of_week": [
          "mon",
          "tue",
          "wed",
          "thu",
          "fri"
        ],
        "start_time": "20:00",
        "end_time": "07:00"
      }
    ],
    "always_allowed_apps": [
      "com.apple.mobilephone",
      "com.apple.MobileSMS",
      "com.apple.Maps"
    ],
    "schedule": {
      "weekday": {
        "start": "07:00",
        "end": "20:00"
      },
      "weekend": {
        "start": "08:00",
        "end": "21:00"
      }
    }
  },
  "purchases": {
    "require_approval": true,
    "block_iap": true,
    "spending_cap_usd": 0
  },
  "privacy": {
    "location_sharing_enabled": true,
    "profile_visibility": "private",
    "account_creation_approval": true,
    "data_sharing_restricted": true
  },
  "social": {
    "chat_mode": "contacts_only",
    "dm_restriction": "disabled",
    "multiplayer_mode": "friends_only"
  },
  "notifications": {
    "curfew_start": "20:00",
    "curfew_end": "07:00",
    "usage_timer_minutes": 30
  },
  "web_filter": {
    "level": "strict",
    "safe_search": true,
    "blocked_domains": [
      "reddit.com",
      "4chan.org"
    ],
    "allowed_domains": [],
    "blocked_categories": [
      "gambling",
      "dating",
      "adult"
    ]
  }
}
POST/device/report

Submit an activity report from the iOS app. Reports are stored in device_reports and fanned out to the activity_logs table for unified analytics. Report types: screen_time (daily usage), app_usage (per-app breakdown), web_activity (browsing history), blocked_attempt (enforcement events), enforcement_status (per-category enforcement results — also updates the device's enforcement_summary for the parent dashboard). Auth: X-Device-Key header.

Request fields

report_type

One of: screen_time, app_usage, web_activity, blocked_attempt, enforcement_status

stringrequired
payload

Report data (varies by report_type). For enforcement_status: { policy_version, results: [{ category, status, framework, detail }] }

objectrequired
reported_at

When the activity occurred on-device

datetimerequired
Requestcurl
curl -X POST https://api.phosra.com/api/v1/device/report \
  -H "X-Device-Key: <device_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "screen_time",
    "payload": {
      "total_minutes": 95,
      "by_category": { "games": 40, "education": 30, "social": 25 },
      "top_apps": [
        { "bundle_id": "com.mojang.minecraftpe", "minutes": 35 },
        { "bundle_id": "com.duolingo", "minutes": 30 }
      ]
    },
    "reported_at": "2026-02-17T20:00:00Z"
  }'
Responsejson
{
  "status": "accepted"
}
POST/device/ack

Confirm that the iOS app has successfully applied a specific policy version. Updates the device's last_policy_version so the parent dashboard can verify enforcement is current. Auth: X-Device-Key header.

Request fields

version

The policy version that was successfully applied

integerrequired
Requestcurl
curl -X POST https://api.phosra.com/api/v1/device/ack \
  -H "X-Device-Key: <device_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "version": 3 }'
Responsejson
{
  "acknowledged_version": 3
}
GET/platform-mappings/{platformID}

Get platform-specific identifier mappings. Currently supports 'apple' — returns Apple age ratings, App Store category bundle IDs, system app bundle IDs, default always-allowed apps, and a category-to-framework mapping that tells the iOS app which Apple framework (ManagedSettings, DeviceActivity, FamilyControls) to use for each Phosra rule category. This endpoint is public and does not require authentication.

Response fields

age_ratings

MPAA/TVPG rating to Apple age rating mapping

object
app_categories

Category → bundle IDs and App Store categories

object
system_apps

System app name → bundle ID (e.g. phone → com.apple.mobilephone)

object
always_allowed

Default always-allowed bundle IDs (Phone, Messages, etc.)

string[]
category_frameworks

Phosra rule category → Apple framework mapping for on-device enforcement

object
Requestcurl
curl https://api.phosra.com/api/v1/platform-mappings/apple
Responsejson
{
  "age_ratings": {
    "G": "4+",
    "PG": "9+",
    "PG-13": "12+",
    "R": "17+",
    "NC-17": "17+",
    "TV-Y": "4+",
    "TV-Y7": "4+",
    "TV-PG": "9+",
    "TV-14": "12+",
    "TV-MA": "17+",
    "E": "4+",
    "E10+": "9+",
    "T": "12+",
    "M": "17+",
    "AO": "17+"
  },
  "app_categories": {
    "social-media": {
      "bundle_ids": [
        "com.burbn.instagram",
        "com.atebits.Tweetie2",
        "com.toyopagroup.picaboo"
      ],
      "app_store_category": "Social Networking"
    },
    "gaming": {
      "bundle_ids": [
        "com.supercell.laser",
        "com.epic.fortnite",
        "com.mojang.minecraftpe"
      ],
      "app_store_category": "Games"
    }
  },
  "system_apps": {
    "phone": "com.apple.mobilephone",
    "messages": "com.apple.MobileSMS",
    "facetime": "com.apple.facetime",
    "maps": "com.apple.Maps",
    "camera": "com.apple.camera"
  },
  "always_allowed": [
    "com.apple.mobilephone",
    "com.apple.MobileSMS",
    "com.apple.facetime",
    "com.apple.Maps"
  ],
  "category_frameworks": {
    "content_rating": {
      "framework": "ManagedSettings",
      "api_class": "ManagedSettingsStore.application",
      "min_os": "16.0"
    },
    "time_daily_limit": {
      "framework": "DeviceActivity",
      "api_class": "DeviceActivitySchedule",
      "min_os": "16.0"
    },
    "web_safesearch": {
      "framework": "ManagedSettings",
      "api_class": "ManagedSettingsStore.webContent.autoFilter",
      "min_os": "16.0"
    },
    "purchase_block_iap": {
      "framework": "ManagedSettings",
      "api_class": "ManagedSettingsStore.appStore.denyInAppPurchases",
      "min_os": "16.0"
    },
    "social_contacts": {
      "framework": "FamilyControls",
      "api_class": "AuthorizationCenter",
      "min_os": "16.0"
    },
    "algo_feed_control": {
      "framework": "none",
      "api_class": "",
      "min_os": "",
      "notes": "Platform-level — no Apple API; enforce by blocking/limiting social apps"
    }
  }
}
Phosra Child Safety Spec (PCSS) v1.0
production·b83294a·main·