Set up a family & kids

Everything Phosra enforces hangs off a child. A child belongs to a family, and carries a policy — the set of rules that get pushed to every connected platform. This guide builds all three in one call, then enforces the result, entirely against the public sandbox.

Every response below is verbatim live output, captured while writing this page. No API key.

Sandbox-first. These requests run against https://phosra-api-sandbox-production.up.railway.app — open, seeded, and safe. In production, change the base URL to https://prodapi.phosra.com and authenticate as the signed-in parent with a WorkOS session JWT — these are consumer routes, so a phosra_ developer key does not work here. The request shapes are identical. See Authentication.

Before you start

bash
export PHOSRA_BASE="https://phosra-api-sandbox-production.up.railway.app/api/v1"
  1. 1
    Create a family, a child, and an active policy — in one call

    POST /setup/quick is the fastest path to a working policy. Give it a child's name, birth date, and a strictness level (recommended, strict, or relaxed). Phosra derives the age group from the birth date and returns a family, a child, an active policy, and a full set of age-appropriate rules — with no follow-up calls.

    bash
    curl -s -X POST "$PHOSRA_BASE/setup/quick" \
  -H "Content-Type: application/json" \
  -d '{
    "child_name": "Emma",
    "birth_date": "2016-03-15",
    "strictness": "recommended"
  }'

    Real response (200), trimmed to the fields you will use:

    json
    {
  "family": { "id": "8581b059-4d30-4f98-88a5-c9667610f5ca", "name": "Emma's Family" },
  "child":  { "id": "1a787ff2-bcd5-4b2d-a5fd-2235ba4e6b9a", "name": "Emma",
              "birth_date": "2016-03-15T00:00:00Z" },
  "policy": { "id": "7949ee63-d113-4405-b791-d400e6e1f97d", "status": "active" },
  "age_group": "preteen",
  "max_ratings": { "mpaa": "PG", "esrb": "E10+", "pegi": "7", "csm": "10+", "tvpg": "TV-PG" },
  "rule_summary": {
    "screen_time_minutes": 120,
    "bedtime_hour": 21,
    "web_filter_level": "moderate",
    "content_rating": "PG",
    "total_rules_enabled": 20
  }
}

    Phosra picked age_group: "preteen" from the 2016 birth date and mapped it to concrete rating ceilings across five rating systems. Store family.id, child.id, and policy.id.

    Change one field to see the age model work. A 2012-09-01 birth date with strictness: "strict" returns age_group: "teen", max_ratings.mpaa: "PG-13", and a lighter web filter — the policy adapts to the child, not to a fixed template.

  2. 2
    Inspect the rules that were generated

    The full response includes a rules array — one entry per enabled rule category, each with its own config. For example, the addictive_design_control rule comes back pre-tuned:

    json
    {
  "id": "6106fd52-48fa-425b-ba4d-df54fcde2704",
  "policy_id": "7949ee63-d113-4405-b791-d400e6e1f97d",
  "category": "addictive_design_control",
  "enabled": true,
  "config": {
    "disable_streaks": true,
    "disable_autoplay": true,
    "disable_like_counts": true,
    "disable_daily_rewards": true,
    "disable_infinite_scroll": true
  }
}

    Every category comes from the canonical rule reference. You can override any of them later with the policy rules API.

  3. 3
    Enforce the policy across connected platforms

    Start a synthetic sandbox job across the family's linked platform fixtures. The job is asynchronous — you get a job back immediately (202 Accepted):

    bash
    curl -s -X POST "$PHOSRA_BASE/children/1a787ff2-bcd5-4b2d-a5fd-2235ba4e6b9a/enforce"

    Real response (202):

    json
    {
  "id": "56072389-470e-4f7c-9d42-1f6cea38d43a",
  "child_id": "1a787ff2-bcd5-4b2d-a5fd-2235ba4e6b9a",
  "policy_id": "7949ee63-d113-4405-b791-d400e6e1f97d",
  "trigger_type": "manual",
  "status": "running"
}

  4. 4
    Confirm the job completed

    Poll the job by id until status is completed. Enforcement does not fire a webhook on completion — poll the job, don't wait for a callback.

    bash
    curl -s "$PHOSRA_BASE/enforcement/jobs/56072389-470e-4f7c-9d42-1f6cea38d43a"

    Real response (200):

    json
    {
  "id": "56072389-470e-4f7c-9d42-1f6cea38d43a",
  "status": "completed",
  "completed_at": "2026-07-06T03:02:11.029Z"
}

    That is the full loop: create → enforce → confirm. For results per platform, read GET /enforcement/jobs/{id}/results — a non-empty manual_steps array means that platform is parent-guided rather than programmatically applied.

Adding more children

Call POST /setup/quick once per child (each returns its own child in the same family when you pass the same family context in production), or use the granular endpoints — POST /families, POST /families/{familyID}/children, POST /policies/{policyID}/generate-from-age — when you need finer control. See the Families and Children reference.

Next steps

Connect a platform

Link a family to a platform so enforcement has somewhere to land.

Test in the sandbox

Understand the open sandbox, the signed Trust List, and self-registration.