API Reference

MindCradle provides a secure REST API for clients to perform authentication, log reflections, retrieve daily insights, and query personal knowledge graphs.

Authentication

All authenticated routes require forwarding the Supabase access token in the authorization headers. Requests without a valid JWT will receive a 401 Unauthorized status.

Authorization: Bearer 

---

Endpoints

1. Mood Check-ins

- POST `/api/mood`: Submit a new mood level and energy reflection. - GET `/api/mood/history`: Retrieve your historical mood logs.

#### Sample Request Payload (POST `/api/mood`)

{
  "mood_score": 8,
  "energy_level": 7,
  "triggers": ["sleep", "work-completed"],
  "note": "Felt very productive today after getting 8 hours of solid sleep."
}

#### Sample Response Payload

{
  "id": "e94c92a2-83b1-417d-8153-73932e6a3281",
  "user_id": "8b7cf8a2-d9d1-4e4b-9fb2-371de2e76f5b",
  "mood_score": 8,
  "energy_level": 7,
  "created_at": "2026-07-30T00:52:10Z"
}

---

2. Search Suggestions

- GET `/api/ai/search/suggestions`: Returns a list of default or personalized example queries to run against your history. (This is a public endpoint).

---

3. AI Insights

- POST `/api/ai/chat`: Send a message to ARIA and receive a relational response grounded in your knowledge graph context.

#### Sample Request Payload

{
  "message": "I'm feeling really anxious about my team presentation tomorrow."
}

#### Sample Response Payload

{
  "reply": "I remember you felt similar anxiety before the marketing launch on June 12, but you noted it resolved within 24 hours. Would you like to try the mindfulness breathing exercise that helped you then?",
  "detected_entities": ["presentation", "anxiety"],
  "updated_nodes": 1
}

- GET `/api/ai/insight`: Get a brief daily summary of your self-awareness patterns and recurring themes.

---

4. User Settings & Exports

- GET `/api/user/export`: Requests a complete download of your personal knowledge graph and timeline records in JSON format. - DELETE `/api/user/account`: Permanently deletes your account and cascades all associated data.

#### Sample Export Response Payload

{
  "export_date": "2026-07-30T00:52:10Z",
  "user_id": "8b7cf8a2-d9d1-4e4b-9fb2-371de2e76f5b",
  "mood_logs_count": 47,
  "journal_entries_count": 28,
  "graph_nodes_count": 12
}