> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phosra.com/llms.txt
> Use this file to discover all available pages before exploring further.
# End-to-end walkthrough
> The full family lifecycle in one page — create a family, browse the catalog, link two platforms, unlink one, and prove per-service isolation. Every call is run live against the open sandbox with real requests and responses, and every screenshot follows the same child (Ruby) and the same streaming link the code makes.
This is the whole journey a family takes through Phosra, start to finish, on a single page.
You will create a family, browse the platform catalog, **link two platforms**, unlink one of
them, watch the other survive untouched, and relink the first — all against the public sandbox.
Every request and response below is **verbatim live output**, captured while writing this page
by running these exact calls against
`https://phosra-api-sandbox-production.up.railway.app`. No API key, nothing to install.
**Sandbox-first.** These calls run against the open partner sandbox with no credential. Nothing
you create touches a real family. The shapes are identical in production — you swap the base URL
for `https://prodapi.phosra.com` and authenticate with a `phosra_live_…` key.
There is one interactive path — the **OAuth connect ceremony** — where a real parent approves in
a browser. Its consent page belongs to the sandbox reference provider and ships its own fixed demo
profiles:
## The ten phases
The load-bearing idea is phases 7–9: **unlinking one platform is scoped to that link alone.**
Deleting the Notflix link does not disturb the second link, and that platform keeps verifying.
There is no cross-service bleed.
## The same journey, in a real app
Before the raw API calls, here is what the ten phases *look like* to a family. Every screen below
is a **real screenshot** captured from Propagate — a reference parental-control app built on this
exact sandbox API — and from a platform's own website. Nothing is mocked or drawn.
**One cast, two names.** The screenshots and the code below follow the **same child** and the
**same streaming link** — only Propagate's playful brand names differ from the public catalog's real
platform ids. Follow the code and you land on the exact UI state each frame shows.
| In the screenshots (Propagate) | In the API calls below | The bridge |
| ------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ruby**, the child | `child_name: "Ruby"` | The same child, end to end. |
| **Notflix** (streaming) | `platform_id: "netflix"` | Notflix is Propagate's stand-in brand for the catalog's **Netflix** — same streaming service, same link/unlink/relink target. |
| **Pixagram** (a second service) | `platform_id: "xbox"` | Pixagram is a social app. The public catalog ships real platform ids and has **no social equivalent**, so the API links `xbox` (a gaming platform) as the second, unrelated service. Both prove the identical point: unlink one, the other survives. |
The family lives in the app: two children (Ruby, Mateo) and the parent as owner. This guide's API
path provisions **Ruby** — the child every later frame follows. This is the `POST /setup/quick`
result — a family plus a child plus a starter policy — rendered for a human.
The catalog of connectable services, grouped by category. `GET /platforms` returns this list.
The link ceremony — the app-side equivalent of `POST /compliance` against `platform_id: "netflix"`.
It states, up front, exactly which rules the platform will apply and confirm before anything turns
green.
The link's detail screen. This is the `status: "verified"` from the compliance response, shown as
a family sees it: **Enforced**, connected today, last synced *just now*.
A second service — **Pixagram**, a social app — is linked. The Services dashboard now reads
**2 of 2 enforced**, the two-managed-platforms state the second `POST /compliance` produces.
(In the API calls this second service is `xbox`: the catalog has no social equivalent for Pixagram,
so xbox stands in — see the cast note above.)
Proof that the link is not cosmetic: **Ruby's** profile **on the streaming platform's own website**
carries a *Managed via Phosra* badge. The rule is enforced where it actually matters.
The family cancels one service. The confirmation is scoped and explicit — it will revoke *only*
this platform's rules. This is the app-side `DELETE /compliance/{linkID}` for the Notflix link.
The unlinked platform reports **Disconnected — rules are no longer applied**, and the platform
itself *confirmed* the removal. Clean teardown, not a silent drop. A **Reconnect** button waits.
The isolation guarantee, made visible: after unlinking one service, the dashboard reads **1 of 1
enforced** — the *other* platform is untouched and still verifying. No cross-service bleed. (In the
screenshots the survivor is **Pixagram**; in the API calls it is `xbox` — the same second, unrelated
service standing in for Pixagram, see the cast note above.)
The family resubscribes and relinks. The platform confirms and protection resumes on a fresh link —
the app-side `POST /compliance` for `netflix` again, closing the loop.
Those are the ten phases as a family experiences them. The rest of this page is the same ten
phases as **API calls** — every request and response run live against the sandbox, following the
same child (**Ruby**) and the same streaming link (**Notflix** → `netflix`).
## Before you start
Set the base URL once so every step is copy-paste:
```bash theme={null}
export PHOSRA_BASE="https://phosra-api-sandbox-production.up.railway.app"
```
This guide uses the **direct compliance link** — the simplest full-lifecycle path, where you
present a platform credential to Phosra. For the interactive **OAuth connect ceremony** (the
consent page above, with `authorize_url` → `token` → `profiles`), see
[Connect a platform](/guides/connect-a-platform). The link/unlink/relink lifecycle below is the
same either way.
One call onboards a family, a child, and an age-appropriate starter policy. `setup/quick` needs
only a child name and birth date. We create **Ruby** — the same child the screenshots follow
([Phase 1](#the-same-journey-in-a-real-app)).
```bash cURL theme={null}
curl -s -X POST "$PHOSRA_BASE/api/v1/setup/quick" \
-H "Content-Type: application/json" \
-d '{
"child_name": "Ruby",
"birth_date": "2018-02-14",
"family_name": "Ruby'\''s Family",
"strictness": "relaxed"
}'
```
```typescript TypeScript theme={null}
const BASE = "https://phosra-api-sandbox-production.up.railway.app";
const res = await fetch(`${BASE}/api/v1/setup/quick`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
child_name: "Ruby",
birth_date: "2018-02-14",
family_name: "Ruby's Family",
strictness: "relaxed",
}),
});
const setup = await res.json();
const familyId = setup.family.id; // carry this into every step below
```
```python Python theme={null}
import requests
BASE = "https://phosra-api-sandbox-production.up.railway.app"
setup = requests.post(
f"{BASE}/api/v1/setup/quick",
json={
"child_name": "Ruby",
"birth_date": "2018-02-14",
"family_name": "Ruby's Family",
"strictness": "relaxed",
},
timeout=30,
).json()
family_id = setup["family"]["id"] # carry this into every step below
```
The response returns the family, the child, and a fully-populated starter policy (**20 rules**
seeded from the `relaxed` preset for an 8-year-old, with the content cap at PG / 7+). Truncated to
the parts you carry forward:
```json theme={null}
{
"family": {
"id": "07617e71-c05d-48a8-942b-53c06b04a2db",
"name": "Ruby's Family",
"created_at": "2026-07-06T09:02:10.028096913Z"
},
"child": {
"id": "5d8d11cb-a5c7-4598-8972-85ef1f248350",
"family_id": "07617e71-c05d-48a8-942b-53c06b04a2db",
"name": "Ruby",
"birth_date": "2018-02-14T00:00:00Z"
},
"policy": {
"id": "c9cfef3c-c556-4b58-bab5-e6f4fcb3ee36",
"name": "Ruby's Protection Policy",
"status": "active"
},
"rule_summary": {
"total_rules_enabled": 20,
"content_rating": "PG",
"web_filter_level": "strict",
"screen_time_minutes": 117
}
}
```
Keep `family.id` — every remaining step is scoped to it.
```bash theme={null}
export FAMILY_ID="07617e71-c05d-48a8-942b-53c06b04a2db"
```
| Field | Type | Notes |
| ------------- | ------ | ------------------------------------------------------------------- |
| `child_name` | string | **Required.** The child's display name. |
| `birth_date` | date | **Required.** `YYYY-MM-DD`. Drives the age-appropriate rule preset. |
| `family_name` | string | Optional. Defaults to `"{child_name}'s Family"`. |
| `strictness` | enum | `recommended` (default), `strict`, or `relaxed`. |
A missing `child_name` or `birth_date` returns `400 { "message": "child_name is required" }`.
Re-running with the same `(family, child_name, birth_date)` de-dupes rather than creating a
duplicate child.
`GET /platforms` returns everything a family can connect — streaming apps, game consoles, DNS
filters, devices, operating systems. No auth.
```bash cURL theme={null}
curl -s "$PHOSRA_BASE/api/v1/platforms"
```
```typescript TypeScript theme={null}
const platforms = await (
await fetch(`${BASE}/api/v1/platforms`)
).json();
// 22 connectable platforms; pick two to link
```
```python Python theme={null}
platforms = requests.get(f"{BASE}/api/v1/platforms", timeout=30).json()
# 22 connectable platforms; pick two to link
```
The live sandbox returns **22 platforms**. Two of them — `netflix` (the streaming service the
screenshots brand **Notflix**) and `xbox` (the second, unrelated service) — are what we link next:
```json theme={null}
[
{ "id": "netflix", "name": "Netflix", "category": "streaming", "enabled": true },
{ "id": "xbox", "name": "Xbox", "category": "gaming", "enabled": true }
]
```
Linking is a single `POST /compliance` with the family, the platform, and a platform credential.
In the sandbox the credential is a demo token; in production it is the real access token you
obtained from the [connect ceremony](/guides/connect-a-platform). This is the API form of the
link ceremony in [Phase 3](#the-same-journey-in-a-real-app).
```bash cURL theme={null}
curl -s -X POST "$PHOSRA_BASE/api/v1/compliance" \
-H "Content-Type: application/json" \
-d "{
\"family_id\": \"$FAMILY_ID\",
\"platform_id\": \"netflix\",
\"credentials\": \"sandbox-demo-token\"
}"
```
```typescript TypeScript theme={null}
const netflix = await (
await fetch(`${BASE}/api/v1/compliance`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
family_id: familyId,
platform_id: "netflix",
credentials: "sandbox-demo-token",
}),
})
).json();
const netflixLinkId = netflix.id; // you unlink and relink with this
```
```python Python theme={null}
netflix = requests.post(
f"{BASE}/api/v1/compliance",
json={
"family_id": family_id,
"platform_id": "netflix",
"credentials": "sandbox-demo-token",
},
timeout=30,
).json()
netflix_link_id = netflix["id"] # you unlink and relink with this
```
The response is the new link. It comes back **`verified`** — Phosra confirmed the credential
against the platform. This is the exact state [Phase 4](#the-same-journey-in-a-real-app) renders
as **Enforced · Applied & verified just now**:
```json theme={null}
{
"id": "5b6d14f3-3ea5-4ae0-a98e-baced770d1df",
"family_id": "07617e71-c05d-48a8-942b-53c06b04a2db",
"platform_id": "netflix",
"status": "verified",
"verified_at": "2026-07-06T09:02:28.396962605Z"
}
```
```bash theme={null}
export NETFLIX_LINK_ID="5b6d14f3-3ea5-4ae0-a98e-baced770d1df"
```
| Field | Type | Notes |
| ------------- | ------ | ----------------------------------------------------------------------------- |
| `family_id` | uuid | **Required.** From step 1. |
| `platform_id` | string | **Required.** A catalog `id` from step 2 (e.g. `netflix`). |
| `credentials` | string | **Required.** Sandbox: any demo token. Production: the platform access token. |
An unknown `platform_id` or malformed `family_id` returns `400`. A duplicate active link for the
same `(family, platform)` returns the existing link rather than a second row.
`GET /families/{id}/compliance` lists every active link for the family. Right now there is one:
```bash cURL theme={null}
curl -s "$PHOSRA_BASE/api/v1/families/$FAMILY_ID/compliance"
```
```typescript TypeScript theme={null}
const links = await (
await fetch(`${BASE}/api/v1/families/${familyId}/compliance`)
).json();
```
```python Python theme={null}
links = requests.get(
f"{BASE}/api/v1/families/{family_id}/compliance", timeout=30
).json()
```
```json theme={null}
[
{
"id": "5b6d14f3-3ea5-4ae0-a98e-baced770d1df",
"family_id": "07617e71-c05d-48a8-942b-53c06b04a2db",
"platform_id": "netflix",
"status": "verified",
"verified_at": "2026-07-06T09:02:28.396962Z"
}
]
```
Repeat the link for a second, unrelated platform. The screenshots show this as a second service
(**Pixagram**, a social app) reaching **2 of 2 enforced** in [Phase 5](#the-same-journey-in-a-real-app);
the public catalog has no social equivalent for Pixagram, so the API links `xbox` — same call,
different `platform_id`.
```bash cURL theme={null}
curl -s -X POST "$PHOSRA_BASE/api/v1/compliance" \
-H "Content-Type: application/json" \
-d "{
\"family_id\": \"$FAMILY_ID\",
\"platform_id\": \"xbox\",
\"credentials\": \"sandbox-demo-token\"
}"
```
```typescript TypeScript theme={null}
const xbox = await (
await fetch(`${BASE}/api/v1/compliance`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
family_id: familyId,
platform_id: "xbox",
credentials: "sandbox-demo-token",
}),
})
).json();
const xboxLinkId = xbox.id;
```
```python Python theme={null}
xbox = requests.post(
f"{BASE}/api/v1/compliance",
json={
"family_id": family_id,
"platform_id": "xbox",
"credentials": "sandbox-demo-token",
},
timeout=30,
).json()
xbox_link_id = xbox["id"]
```
```json theme={null}
{
"id": "96d4b117-7711-4527-9c4a-e6e13b7094ff",
"family_id": "07617e71-c05d-48a8-942b-53c06b04a2db",
"platform_id": "xbox",
"status": "verified",
"verified_at": "2026-07-06T09:02:28.913726803Z"
}
```
```bash theme={null}
export XBOX_LINK_ID="96d4b117-7711-4527-9c4a-e6e13b7094ff"
```
The family now manages **two** verified links — the `2/2 enforced` dashboard state of
[Phase 5](#the-same-journey-in-a-real-app). The same list call returns both:
```bash cURL theme={null}
curl -s "$PHOSRA_BASE/api/v1/families/$FAMILY_ID/compliance"
```
```typescript TypeScript theme={null}
const managed = await (
await fetch(`${BASE}/api/v1/families/${familyId}/compliance`)
).json();
// managed.length === 2 → [netflix, xbox]
```
```python Python theme={null}
managed = requests.get(
f"{BASE}/api/v1/families/{family_id}/compliance", timeout=30
).json()
# len(managed) == 2 → [netflix, xbox]
```
```json theme={null}
[
{
"id": "5b6d14f3-3ea5-4ae0-a98e-baced770d1df",
"platform_id": "netflix",
"status": "verified",
"verified_at": "2026-07-06T09:02:28.396962Z"
},
{
"id": "96d4b117-7711-4527-9c4a-e6e13b7094ff",
"platform_id": "xbox",
"status": "verified",
"verified_at": "2026-07-06T09:02:28.913726Z"
}
]
```
The family cancels Notflix — the [Phase 7](#the-same-journey-in-a-real-app) "Disconnect Notflix?"
dialog. Delete **only** the Netflix link by its `linkID`. A successful teardown returns
`204 No Content` — no body.
```bash cURL theme={null}
curl -s -o /dev/null -w "%{http_code}\n" \
-X DELETE "$PHOSRA_BASE/api/v1/compliance/$NETFLIX_LINK_ID"
# → 204
```
```typescript TypeScript theme={null}
const res = await fetch(`${BASE}/api/v1/compliance/${netflixLinkId}`, {
method: "DELETE",
});
// res.status === 204
```
```python Python theme={null}
res = requests.delete(
f"{BASE}/api/v1/compliance/{netflix_link_id}", timeout=30
)
# res.status_code == 204
```
```
HTTP/1.1 204 No Content
```
The delete is keyed on the **link's** `id`, not the platform or the family. It removes exactly
one link. This is what makes the next step true.
List the family's links again. Netflix is gone; **the xbox link is untouched** — the
`1/1 enforced` survivor state of [Phase 9](#the-same-journey-in-a-real-app):
```bash cURL theme={null}
curl -s "$PHOSRA_BASE/api/v1/families/$FAMILY_ID/compliance"
```
```typescript TypeScript theme={null}
const afterUnlink = await (
await fetch(`${BASE}/api/v1/families/${familyId}/compliance`)
).json();
// afterUnlink.length === 1 → [xbox]
```
```python Python theme={null}
after_unlink = requests.get(
f"{BASE}/api/v1/families/{family_id}/compliance", timeout=30
).json()
# len(after_unlink) == 1 → [xbox]
```
```json theme={null}
[
{
"id": "96d4b117-7711-4527-9c4a-e6e13b7094ff",
"family_id": "07617e71-c05d-48a8-942b-53c06b04a2db",
"platform_id": "xbox",
"status": "verified",
"verified_at": "2026-07-06T09:02:28.913726Z"
}
]
```
Isolation is not just "the xbox link is still listed" — it is "it still **works**." Verify the
Xbox link after the Netflix teardown and it re-confirms clean:
```bash cURL theme={null}
curl -s -X POST "$PHOSRA_BASE/api/v1/compliance/$XBOX_LINK_ID/verify" \
-H "Content-Type: application/json" -d '{}'
```
```typescript TypeScript theme={null}
const check = await (
await fetch(`${BASE}/api/v1/compliance/${xboxLinkId}/verify`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: "{}",
})
).json();
// check.status === "verified"
```
```python Python theme={null}
check = requests.post(
f"{BASE}/api/v1/compliance/{xbox_link_id}/verify",
json={},
timeout=30,
).json()
# check["status"] == "verified"
```
```json theme={null}
{ "status": "verified" }
```
Removing Netflix had zero effect on the Xbox link — a different platform's enforcement kept running
the whole time. This is the guarantee real households depend on: cancelling one service never
quietly drops protection on another.
The family resubscribes — the [Phase 10](#the-same-journey-in-a-real-app) "Notflix connected ·
Protecting Ruby" success screen. Relinking is just the link call again — and because the earlier
delete fully released the old link, you get a **fresh** `linkID` (note it differs from step 3):
```bash cURL theme={null}
curl -s -X POST "$PHOSRA_BASE/api/v1/compliance" \
-H "Content-Type: application/json" \
-d "{
\"family_id\": \"$FAMILY_ID\",
\"platform_id\": \"netflix\",
\"credentials\": \"sandbox-demo-token\"
}"
```
```typescript TypeScript theme={null}
const relinked = await (
await fetch(`${BASE}/api/v1/compliance`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
family_id: familyId,
platform_id: "netflix",
credentials: "sandbox-demo-token",
}),
})
).json();
// relinked.id !== netflixLinkId → a brand-new link
```
```python Python theme={null}
relinked = requests.post(
f"{BASE}/api/v1/compliance",
json={
"family_id": family_id,
"platform_id": "netflix",
"credentials": "sandbox-demo-token",
},
timeout=30,
).json()
# relinked["id"] != netflix_link_id → a brand-new link
```
```json theme={null}
{
"id": "28163206-1de7-4d76-b40b-302a5296846b",
"family_id": "07617e71-c05d-48a8-942b-53c06b04a2db",
"platform_id": "netflix",
"status": "verified",
"verified_at": "2026-07-06T09:02:30.111746394Z"
}
```
The family is back to two managed platforms, with Netflix on a new link (`28163206…`, up from the
released `5b6d14f3…`) and Xbox on the same one it has had the entire time.
## The whole flow at a glance
Every row below is one call you just ran, in order — the same **Ruby** family the screenshots
follow:
| # | Phase | Call | Live result |
| -- | ------------------------ | ---------------------------------- | ---------------------------------------------- |
| 1 | Create the family | `POST /setup/quick` | family `07617e71…`, child Ruby, 20-rule policy |
| 2 | Browse the catalog | `GET /platforms` | 22 connectable platforms |
| 3 | Link Notflix (`netflix`) | `POST /compliance` | link `5b6d14f3…`, `verified` |
| 4 | Confirm the link | `GET /families/{id}/compliance` | `[netflix]` |
| 5 | Link second (`xbox`) | `POST /compliance` | link `96d4b117…`, `verified` |
| 6 | See both managed | `GET /families/{id}/compliance` | `[netflix, xbox]` |
| 7 | Unlink Notflix | `DELETE /compliance/{linkID}` | `204 No Content` |
| 8 | Confirm release | `GET /families/{id}/compliance` | `[xbox]` — Netflix gone |
| 9 | Survivor survived | `POST /compliance/{linkID}/verify` | `{ "status": "verified" }` |
| 10 | Relink Notflix | `POST /compliance` | new link `28163206…`, `verified` |
## Next steps
The interactive OAuth connect ceremony behind the consent page — `authorize_url` → token → profiles.
The decline path, the production teardown, and clean re-approval in depth.
Manage children, policies, and rules on the family you just created.
The seeded reference providers and Trust List these calls run against.