InClasso API Documentation

Build safe, engaging applications for children with our comprehensive REST API. Complete with COPPA compliance, content moderation, and parental controls.

99.9%

Uptime SLA

10K+

Developers

COPPA

Compliant

1. Introduction

The InClasso API provides a comprehensive set of endpoints for building child-safe social applications. Our API handles user management, content moderation, parental controls, and friend connections with built-in COPPA compliance.

Base URL

https://api.inclasso.com/v1

Versioning

The API is versioned in the URL path. Breaking changes ship under a new version; old versions are supported for 12 months after deprecation.

2. Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header of your requests.

Header Format

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET "https://api.inclasso.com/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

3. API Endpoints

All endpoints are JSON over HTTPS. Read endpoints accept page and per_page query parameters and return a Link header following RFC 5988. Mutating endpoints require an Idempotency-Key header to guarantee safe retries.

Resource families

/users — adult accounts (parents, teachers, principals)
/children — under-18 profiles, parent-supervised
/posts, /comments — moderated user content
/moderation — reports, reviews, scan results
/webhooks — outbound event subscriptions

Rate limits

Default: 60 requests / minute per API key
Bulk / list endpoints: 30 / minute
Webhook delivery retries: exponential backoff over 24h

429 responses include Retry-After in seconds.

See the per-resource sections below for full schemas.

4. User Management

Adult accounts on InClasso. The role field is one of parent, teacher, principal, or creator. Child accounts live under /children.

GET/users

List users (paginated)

{
  "users": [
    {
      "id": "user_123",
      "email": "parent@example.com",
      "role": "parent",
      "children_count": 2,
      "email_verified_at": "2024-01-15T10:31:42Z",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "per_page": 25,
  "total": 1
}

POST/users

Create an adult user (email verification required)

Request body

{
  "email": "parent@example.com",
  "password": "use-a-strong-passphrase",
  "role": "parent",
  "accepted_terms_version": "2026-05-01"
}

201 Response

{
  "id": "user_456",
  "email": "parent@example.com",
  "role": "parent",
  "email_verified_at": null,
  "verification_email_sent_to": "parent@example.com",
  "created_at": "2026-05-14T20:10:00Z"
}

PATCH/users/{id}

Update profile fields (partial)

{
  "display_name": "Alex Parent",
  "notification_preferences": {
    "email_digest": "weekly",
    "moderation_alerts": "immediate"
  }
}

DELETE/users/{id}

GDPR erasure — cascades to attached children

Returns 202 Accepted. Erasure runs asynchronously and emits a user.erased webhook when complete. The user's authored content is anonymized rather than removed so that moderation history remains auditable.

5. Child Profiles

Child profiles always belong to an adult guardian. Every write requires a one-time parental_consent_token obtained from the consent flow at /auth/parental-consent.

COPPA note. Profiles with age < 13 never expose email, phone, or precise location fields in API responses, even to the parent. Use the privacy-preserving fields documented below.

GET/children?parent_id={id}

List child profiles for a guardian

{
  "children": [
    {
      "id": "child_789",
      "parent_id": "user_123",
      "display_name": "Alice",
      "age_band": "8-10",
      "supervised": true,
      "consent_token_expires_at": "2027-05-14T00:00:00Z",
      "created_at": "2026-01-10T09:00:00Z"
    }
  ]
}

POST/children

Create profile (consent token required)

Request body

{
  "parent_id": "user_123",
  "display_name": "Alice",
  "age": 8,
  "parental_consent_token": "pct_01HXYZ...",
  "supervised": true
}

Error: invalid consent token

HTTP/1.1 422 Unprocessable Entity
{
  "error": "consent_token_invalid",
  "message": "Parental consent token is expired, revoked, or already used.",
  "consent_flow_url": "https://api.inclasso.com/v1/auth/parental-consent"
}

PATCH/children/{id}/supervision

Adjust parental controls

{
  "daily_screen_time_minutes": 45,
  "chat_mode": "approved_contacts_only",
  "content_filter": "strict",
  "post_review_required": true
}

6. Content Moderation

InClasso runs automated scans on every user-generated content item (posts, comments, images, profile fields) and routes anything that crosses a threshold to human reviewers. Your application can read moderation outcomes and submit user reports through these endpoints.

POST/moderation/reports

User-submitted report

Request body

{
  "target_type": "post",
  "target_id": "post_5f7a...",
  "reporter_id": "user_123",
  "category": "bullying",
  "description": "Repeated put-downs aimed at my child in the class feed.",
  "evidence_urls": ["https://media.inclasso.com/.../screenshot.png"]
}

202 Response

{
  "report_id": "rep_01HXYZ...",
  "status": "queued",
  "sla_minutes": 60,
  "case_url": "https://app.inclasso.com/safety/cases/rep_01HXYZ..."
}

GET/moderation/scan-results/{content_id}

Read the automated scan verdict

{
  "content_id": "post_5f7a...",
  "verdict": "review_required",
  "confidence": 0.78,
  "signals": [
    { "label": "bullying_language", "score": 0.81 },
    { "label": "personal_information", "score": 0.12 }
  ],
  "reviewed_by": null,
  "reviewed_at": null
}

POST/moderation/reviews

Staff-only — submit a human review decision

{
  "report_id": "rep_01HXYZ...",
  "decision": "remove",
  "action": "hide_content_and_warn_author",
  "internal_notes": "Targeted harassment, prior warning on 2026-04-30."
}

Authorization. Submitting a report requires the reporter's user token. Reading scan results requires either ownership of the content or a staff role. Creating a review (POST /moderation/reviews) requires the moderator scope.

7. Webhooks

InClasso pushes events to your HTTPS endpoint as JSON over POST. Deliveries are signed, idempotent (via X-InClasso-Event-Id), and retried with exponential backoff for up to 24 hours on any non-2xx response.

POST/webhooks

Request body

{
  "url": "https://yourapp.example.com/inclasso-events",
  "events": [
    "user.created",
    "child.profile.created",
    "moderation.alert",
    "content.removed"
  ],
  "description": "Production webhook"
}

201 Response

{
  "id": "wh_01HXYZ...",
  "url": "https://yourapp.example.com/inclasso-events",
  "signing_secret": "whsec_REDACTED_SHOWN_ONCE",
  "events": ["user.created", "child.profile.created", "moderation.alert", "content.removed"],
  "created_at": "2026-05-14T20:12:00Z"
}

Save signing_secret now — it is shown only on creation and cannot be retrieved later.

Event envelope

POST /inclasso-events HTTP/1.1
Content-Type: application/json
X-InClasso-Event-Id: evt_01HXYZ...
X-InClasso-Event-Type: moderation.alert
X-InClasso-Signature: t=1715724720,v1=ce8b3...

{
  "id": "evt_01HXYZ...",
  "type": "moderation.alert",
  "created_at": "2026-05-14T20:12:00Z",
  "data": {
    "content_id": "post_5f7a...",
    "verdict": "remove",
    "categories": ["bullying"],
    "child_id": "child_789"
  }
}

Verifying the signature

Compute HMAC-SHA256(signing_secret, "{t}.{raw_body}") and compare in constant time to the v1 value in the header. Reject deliveries older than 5 minutes.

import crypto from 'crypto';

export function verifyInClassoSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(',').map(kv => kv.split('='))
  );
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');
  const ok = crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(parts.v1, 'hex')
  );
  const fresh = Date.now() / 1000 - Number(parts.t) < 300;
  return ok && fresh;
}

Event catalogue

Event	Fires when
`user.created`	A new adult account is created.
`user.erased`	GDPR erasure has finished for a user.
`child.profile.created`	A guardian completes the consent flow and creates a child profile.
`child.supervision.changed`	Screen time, chat mode, or content filter is updated.
`moderation.alert`	Automated scan or human review flags content above the threshold.
`content.removed`	Moderation has removed a post, comment, or media item.
`parental_consent.granted`	A guardian grants or renews parental consent for a child.

8. Error Handling

The API uses conventional HTTP response codes to indicate success or failure of requests.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "validation_failed",
  "message": "Email is already in use.",
  "field_errors": {
    "email": ["already_in_use"]
  },
  "request_id": "req_01HXYZ..."
}

4xx Client errors

400 — Bad Request

401 — Missing or invalid API key

403 — Authenticated but lacks scope (e.g. moderator)

404 — Resource not found

409 — State conflict (e.g. duplicate)

422 — Validation failed (see field_errors)

429 — Rate limited (see Retry-After)

5xx Server errors

500 — Internal Server Error (please retry with the request_id)

502 — Bad Gateway

503 — Service Unavailable (planned maintenance announced 7 days ahead)

504 — Gateway Timeout

5xx responses are safe to retry with the same Idempotency-Key.

9. SDK & Libraries

Official SDKs wrap the API, handle retries with idempotency keys, verify webhook signatures, and ship typed models for every resource.

JavaScript / Node.js

npm install @inclasso/sdk

import { InClasso } from '@inclasso/sdk';
const ic = new InClasso({ apiKey: process.env.INCLASSO_KEY });
const user = await ic.users.create({ email, password, role: 'parent' });

Python

pip install inclasso-sdk

from inclasso import InClasso
ic = InClasso(api_key=os.environ["INCLASSO_KEY"])
user = ic.users.create(email=email, password=password, role="parent")

InClasso API Documentation

Build safe, engaging applications for children with our comprehensive REST API. Complete with COPPA compliance, content moderation, and parental controls.

99.9%

Uptime SLA

10K+

Developers

COPPA

Compliant

1. Introduction

Base URL

https://api.inclasso.com/v1

Versioning

The API is versioned in the URL path. Breaking changes ship under a new version; old versions are supported for 12 months after deprecation.

2. Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header of your requests.

Header Format

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET "https://api.inclasso.com/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

3. API Endpoints

Resource families

/users — adult accounts (parents, teachers, principals)
/children — under-18 profiles, parent-supervised
/posts, /comments — moderated user content
/moderation — reports, reviews, scan results
/webhooks — outbound event subscriptions

Rate limits

Default: 60 requests / minute per API key
Bulk / list endpoints: 30 / minute
Webhook delivery retries: exponential backoff over 24h

429 responses include Retry-After in seconds.

See the per-resource sections below for full schemas.

4. User Management

Adult accounts on InClasso. The role field is one of parent, teacher, principal, or creator. Child accounts live under /children.

GET/users

List users (paginated)

{
  "users": [
    {
      "id": "user_123",
      "email": "parent@example.com",
      "role": "parent",
      "children_count": 2,
      "email_verified_at": "2024-01-15T10:31:42Z",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "per_page": 25,
  "total": 1
}

POST/users

Create an adult user (email verification required)

Request body

{
  "email": "parent@example.com",
  "password": "use-a-strong-passphrase",
  "role": "parent",
  "accepted_terms_version": "2026-05-01"
}

201 Response

{
  "id": "user_456",
  "email": "parent@example.com",
  "role": "parent",
  "email_verified_at": null,
  "verification_email_sent_to": "parent@example.com",
  "created_at": "2026-05-14T20:10:00Z"
}

PATCH/users/{id}

Update profile fields (partial)

{
  "display_name": "Alex Parent",
  "notification_preferences": {
    "email_digest": "weekly",
    "moderation_alerts": "immediate"
  }
}

DELETE/users/{id}

GDPR erasure — cascades to attached children

5. Child Profiles

Child profiles always belong to an adult guardian. Every write requires a one-time parental_consent_token obtained from the consent flow at /auth/parental-consent.

COPPA note. Profiles with age < 13 never expose email, phone, or precise location fields in API responses, even to the parent. Use the privacy-preserving fields documented below.

GET/children?parent_id={id}

List child profiles for a guardian

{
  "children": [
    {
      "id": "child_789",
      "parent_id": "user_123",
      "display_name": "Alice",
      "age_band": "8-10",
      "supervised": true,
      "consent_token_expires_at": "2027-05-14T00:00:00Z",
      "created_at": "2026-01-10T09:00:00Z"
    }
  ]
}

POST/children

Create profile (consent token required)

Request body

{
  "parent_id": "user_123",
  "display_name": "Alice",
  "age": 8,
  "parental_consent_token": "pct_01HXYZ...",
  "supervised": true
}

Error: invalid consent token

HTTP/1.1 422 Unprocessable Entity
{
  "error": "consent_token_invalid",
  "message": "Parental consent token is expired, revoked, or already used.",
  "consent_flow_url": "https://api.inclasso.com/v1/auth/parental-consent"
}

PATCH/children/{id}/supervision

Adjust parental controls

{
  "daily_screen_time_minutes": 45,
  "chat_mode": "approved_contacts_only",
  "content_filter": "strict",
  "post_review_required": true
}

6. Content Moderation

POST/moderation/reports

User-submitted report

Request body

{
  "target_type": "post",
  "target_id": "post_5f7a...",
  "reporter_id": "user_123",
  "category": "bullying",
  "description": "Repeated put-downs aimed at my child in the class feed.",
  "evidence_urls": ["https://media.inclasso.com/.../screenshot.png"]
}

202 Response

{
  "report_id": "rep_01HXYZ...",
  "status": "queued",
  "sla_minutes": 60,
  "case_url": "https://app.inclasso.com/safety/cases/rep_01HXYZ..."
}

GET/moderation/scan-results/{content_id}

Read the automated scan verdict

{
  "content_id": "post_5f7a...",
  "verdict": "review_required",
  "confidence": 0.78,
  "signals": [
    { "label": "bullying_language", "score": 0.81 },
    { "label": "personal_information", "score": 0.12 }
  ],
  "reviewed_by": null,
  "reviewed_at": null
}

POST/moderation/reviews

Staff-only — submit a human review decision

{
  "report_id": "rep_01HXYZ...",
  "decision": "remove",
  "action": "hide_content_and_warn_author",
  "internal_notes": "Targeted harassment, prior warning on 2026-04-30."
}

7. Webhooks

POST/webhooks

Request body

{
  "url": "https://yourapp.example.com/inclasso-events",
  "events": [
    "user.created",
    "child.profile.created",
    "moderation.alert",
    "content.removed"
  ],
  "description": "Production webhook"
}

201 Response

{
  "id": "wh_01HXYZ...",
  "url": "https://yourapp.example.com/inclasso-events",
  "signing_secret": "whsec_REDACTED_SHOWN_ONCE",
  "events": ["user.created", "child.profile.created", "moderation.alert", "content.removed"],
  "created_at": "2026-05-14T20:12:00Z"
}

Save signing_secret now — it is shown only on creation and cannot be retrieved later.

Event envelope

POST /inclasso-events HTTP/1.1
Content-Type: application/json
X-InClasso-Event-Id: evt_01HXYZ...
X-InClasso-Event-Type: moderation.alert
X-InClasso-Signature: t=1715724720,v1=ce8b3...

{
  "id": "evt_01HXYZ...",
  "type": "moderation.alert",
  "created_at": "2026-05-14T20:12:00Z",
  "data": {
    "content_id": "post_5f7a...",
    "verdict": "remove",
    "categories": ["bullying"],
    "child_id": "child_789"
  }
}

Verifying the signature

Compute HMAC-SHA256(signing_secret, "{t}.{raw_body}") and compare in constant time to the v1 value in the header. Reject deliveries older than 5 minutes.

import crypto from 'crypto';

export function verifyInClassoSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(',').map(kv => kv.split('='))
  );
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');
  const ok = crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(parts.v1, 'hex')
  );
  const fresh = Date.now() / 1000 - Number(parts.t) < 300;
  return ok && fresh;
}

Event catalogue

Event	Fires when
`user.created`	A new adult account is created.
`user.erased`	GDPR erasure has finished for a user.
`child.profile.created`	A guardian completes the consent flow and creates a child profile.
`child.supervision.changed`	Screen time, chat mode, or content filter is updated.
`moderation.alert`	Automated scan or human review flags content above the threshold.
`content.removed`	Moderation has removed a post, comment, or media item.
`parental_consent.granted`	A guardian grants or renews parental consent for a child.

8. Error Handling

The API uses conventional HTTP response codes to indicate success or failure of requests.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "validation_failed",
  "message": "Email is already in use.",
  "field_errors": {
    "email": ["already_in_use"]
  },
  "request_id": "req_01HXYZ..."
}

4xx Client errors

400 — Bad Request

401 — Missing or invalid API key

403 — Authenticated but lacks scope (e.g. moderator)

404 — Resource not found

409 — State conflict (e.g. duplicate)

422 — Validation failed (see field_errors)

429 — Rate limited (see Retry-After)

5xx Server errors

500 — Internal Server Error (please retry with the request_id)

502 — Bad Gateway

503 — Service Unavailable (planned maintenance announced 7 days ahead)

504 — Gateway Timeout

5xx responses are safe to retry with the same Idempotency-Key.

9. SDK & Libraries

Official SDKs wrap the API, handle retries with idempotency keys, verify webhook signatures, and ship typed models for every resource.

JavaScript / Node.js

npm install @inclasso/sdk

import { InClasso } from '@inclasso/sdk';
const ic = new InClasso({ apiKey: process.env.INCLASSO_KEY });
const user = await ic.users.create({ email, password, role: 'parent' });

Python

pip install inclasso-sdk

from inclasso import InClasso
ic = InClasso(api_key=os.environ["INCLASSO_KEY"])
user = ic.users.create(email=email, password=password, role="parent")