FamilyNest API Reference

Welcome to the FamilyNest REST API. This documentation covers all available endpoints for building applications that integrate with our parenting and family support platform. The API follows standard REST conventions, uses JSON for request/response bodies, and supports Bearer token authentication.

🔗 Base URL https://api.familynest.com/v1

Authentication

All API requests require authentication via a Bearer token in the `Authorization` header. Tokens are generated from your developer dashboard and can be scoped to specific permissions.

Header

Authorization: Bearer <YOUR_API_TOKEN>

Token Scopes

Scope	Description
`read:profile`	Read family and user profiles
`write:tracker`	Create/update pregnancy & milestone trackers
`read:content`	Access articles, activities, and guides
`write:community`	Post to forums and community groups

Endpoints

👨‍👩‍👧‍👦 Families

GET /families/{family_id} Retrieve family profile

Returns detailed information about a specific family account, including members, preferences, and active trackers.

Parameter	Type	Description
`family_id`	string	Unique family identifier required

Response 200

{
  "id": "fam_8x92k1",
  "name": "The Rodriguez Family",
  "members": 3,
  "stage": "toddler",
  "created_at": "2023-04-12T14:30:00Z",
  "preferences": {"notifications": true, "theme": "light"}
}

🤰 Pregnancy & Tracking

POST /pregnancy/trackers Create pregnancy tracker

Initializes a new pregnancy tracking journey for a family member. Requires `write:tracker` scope.

Parameter	Type	Description
`expected_date`	string	ISO 8601 due date required
`start_date`	string	Pregnancy start date required
`notes`	string	Initial notes or medical details

Request Body

{
  "expected_date": "2024-11-15",
  "start_date": "2024-02-10",
  "notes": "First trimester, low risk."
}

🎨 Kids Activities

GET /activities List age-appropriate activities

Fetches educational and creative activities filtered by child age, category, and difficulty.

Parameter	Type	Description
`age`	integer	Child's age in years required
`category`	string	craft, learning, outdoor, sensory
`limit`	integer	Max results (default: 20)

👥 Community & Forums

POST /community/forums/{forum_id}/posts Create community post

Submits a new discussion post to a moderated parenting forum. Requires `write:community` scope.

Parameter	Type	Description
`forum_id`	string	Target forum identifier required
`title`	string	Post title required
`body`	string	Markdown-formatted content required

API Playground

Test endpoints directly from your browser. The playground simulates API responses locally for documentation purposes.

Endpoint

Request Body (JSON)

// Response will appear here...

Rate Limits

API requests are throttled to ensure platform stability. Limits are applied per API token.

Plan	Requests / Minute	Requests / Day	Burst Limit
Free	100	5,000	15
Developer	500	50,000	50
Enterprise	2,000	Unlimited	200

Exceeding limits returns 429 Too Many Requests with a Retry-After header.

Error Codes

FamilyNest uses standard HTTP status codes to indicate success or failure. Error responses include a machine-readable code and human-readable message.

Code	Status	Description
`400`	Bad Request	Invalid syntax or missing required parameters
`401`	Unauthorized	Missing or invalid authentication token
`403`	Forbidden	Token lacks required scope for this resource
`404`	Not Found	Requested resource does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Error	Unexpected server-side failure

Error Response

{
  "error": {
    "code": 401,
    "message": "Invalid or expired API token.",
    "docs": "https://docs.familynest.com/errors/401"
  }
}

Webhooks

Subscribe to real-time events in your family dashboard. Webhooks are delivered via HTTPS POST with HMAC signature verification.

Payload Example

{
  "event": "tracker.milestone_reached",
  "timestamp": "2024-05-20T09:14:00Z",
  "data": {
    "family_id": "fam_8x92k1",
    "milestone": "first_steps",
    "age_weeks": 11
  }
}