> ## 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.

# Policies & Rules

> How policies organize rules across 117 OCSS rule categories

# Policies & Rules

A **policy** is a named collection of rules assigned to a child. Policies have a status (`draft`, `active`, or `paused`) and a priority number for ordering when multiple policies exist.

A **rule** belongs to a policy and controls one of **117 rule categories** — the closed OCSS v4 vocabulary (`internal/domain/models.go`, canonical registry at `registry/ocss-rules.json`). Each rule has:

* **category** — which of the 117 categories it controls (e.g., `time_daily_limit`, `content_rating`)
* **enabled** — whether this rule is active
* **config** — category-specific configuration JSON (e.g., `{"max_ratings":{"mpaa":"PG-13"}}` for content rating)

Only **active** policies are enforced. You can have multiple policies per child (e.g., "School Day" and "Weekend") and switch between them using activate/pause.

## Quick setup

The fastest path: `POST /api/v1/setup/quick` creates a family, child, and active policy in one call. Pass `child_name`, `birth_date`, and `strictness` (`light`, `recommended`, `strict`). The response includes `max_ratings`, `rule_summary`, and the full `rules[]` array.

```bash theme={null}
curl -X POST https://prodapi.phosra.com/api/v1/setup/quick \
  -H "Authorization: Bearer $PHOSRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "child_name": "Emma",
    "birth_date": "2016-03-15",
    "strictness": "recommended"
  }'
```

## Bulk upsert rules

`PUT /api/v1/policies/{policyId}/rules/bulk` creates or updates multiple rules in one call. The developer surface is identical: `PUT /api/v1/developer/policies/{policyId}/rules/bulk`.

**Request body:**

```json theme={null}
{
  "rules": [
    {
      "category": "content_rating",
      "enabled": true,
      "config": {
        "max_ratings": {
          "mpaa": "PG-13",
          "tv": "TV-Y7",
          "esrb": "E"
        }
      }
    },
    {
      "category": "time_daily_limit",
      "enabled": true,
      "config": {
        "daily_minutes": 120
      }
    },
    {
      "category": "web_safesearch",
      "enabled": true,
      "config": {}
    }
  ]
}
```

**Response:** `[]PolicyRule` — the full updated rule set for the policy.

### Config shapes for common categories

| Category               | Config field                          | Example value                                                         |
| ---------------------- | ------------------------------------- | --------------------------------------------------------------------- |
| `content_rating`       | `max_ratings` (object)                | `{"mpaa":"PG-13","tv":"TV-Y7","esrb":"E","pegi":"12"}`                |
| `time_daily_limit`     | `daily_minutes` (int)                 | `{"daily_minutes":120}`                                               |
| `time_scheduled_hours` | `schedule` (array of hour ranges)     | `{"schedule":[{"days":["mon","tue"],"start":"07:00","end":"21:00"}]}` |
| `time_downtime`        | `start_hour`, `end_hour` (ints, 0-23) | `{"start_hour":22,"end_hour":7}`                                      |
| `web_filter_level`     | `level` (string)                      | `{"level":"strict"}`                                                  |
| `web_category_block`   | `categories` (array of strings)       | `{"categories":["adult","gambling"]}`                                 |

## Rule categories

The **117** closed OCSS v4 categories span:

* **Content** — `content_rating`, `content_block_title`, `violence_threshold`, `firearm_content_block`, `sexual_content_threshold`, and 10 more
* **Time** — `time_daily_limit`, `time_scheduled_hours`, `time_per_app_limit`, `time_downtime`, `phone_free_school_hours`
* **Purchase** — `purchase_approval`, `purchase_spending_cap`, `purchase_block_iap`
* **Social** — `social_contacts`, `social_chat_control`, `social_multiplayer`, `stranger_dm_block`, `stranger_outreach_friction`
* **Web** — `web_safesearch`, `web_category_block`, `web_custom_allowlist`, `web_custom_blocklist`, `web_filter_level`
* **Privacy** — `privacy_location`, `privacy_profile_visibility`, `privacy_data_sharing`, `data_minimization_enforce`, `third_party_tracker_block`, and more
* **Monitoring** — `monitoring_activity`, `monitoring_alerts`, content-monitoring categories
* **Algorithmic Safety** — `algo_feed_control`, `addictive_design_control`, `infinite_scroll_block`, `autoplay_disable`, and more
* **Notifications** — `notification_curfew`, `usage_timer_notification`
* **Advertising / Data** — `targeted_ad_block`, `dm_restriction`, `age_gate`, `data_deletion_request`
* **Age Assurance** — `app_store_age_attestation`, `os_age_signal_ingest`, `age_signal_broadcast`, `parental_attestation_cert`
* **AI Safety** — `ai_chatbot_tier_gate`, `ai_no_simulated_companionship`, `ai_chatbot_age_assertion`, and 12 more
* **Compliance** — `csam_reporting`, `social_media_min_age`, `student_privacy_school_mode`, and more
* **Legislation-driven** — `parental_consent_gate`, `parental_event_notification`, `screen_time_report`, `commercial_data_ban`, and more
* **Integration surface** — `age_appropriate_profile_mode`, `ncii_takedown`, `adult_site_av_required`, `app_install_block`, `cipa_filter_attestation`, and more

See `GET /api/v1/standards` for community packs that pre-configure curated subsets of these categories.

## Related API Endpoints

* [Create a policy](/developers/api-reference/policies/post-children-policies) — Create a new policy for a child
* [Generate rules from age](/developers/api-reference/policies/post-policies-generate-from-age) — Auto-populate all 117 rule categories
* [Bulk upsert rules](/developers/api-reference/rules/put-policies-rules-bulk) — Create or update multiple rules in one call
* [Activate a policy](/developers/api-reference/policies/post-policies-activate) — Set a policy as active for enforcement