GreenDial API

REST API — base URL: https://greendial.org · All endpoints return JSON unless noted.

✨ How It Works — 10 Examples 📄 OpenAPI 3.1 Spec 🔀 Arazzo Workflow Spec ⚙️ Source on GitHub

Overview

GreenDial is a personal health platform powered by Doc, a primary AI coordinator, and a team of specialist health agents. Doc guides conversations, builds the user's health profile, and routes domain-specific questions to the right agent. When a message matches two or more agent domains, Cross AI synthesizes perspectives from multiple specialists in parallel.

Agents also run on a server-side cron schedule (08:00 UTC daily), generating personalized check-in notifications for subscribed users. Each agent has its own dedicated chat tab in the UI, with a profile-building onboarding interview on first activation.

Authentication is username + passphrase for the app; HTTP Basic Auth for third-party integrations.

Agent roster

ID	Name	Domain
diet	🥗 Diet	Nutrition, eating habits, weight management, hydration
exercise	💪 Exercise	Fitness, movement, workouts, injury prevention
protect	🛡️ Protect AI	Immune resilience + disease prevention, screenings, risk factors
sleep	😴 Sleep	Sleep quality, insomnia, circadian rhythm, sleep hygiene
mental_health	🧠 Mind	Stress, anxiety, depression, mindfulness, resilience
relationships	💞 Relationships	Social connection, communication, loneliness, caregiving
environment	🌍 Environment	Air quality, ergonomics, home/workplace health, nature
custom	⚙️ Custom	User-defined system prompt — any health topic
cross_ai	🔀 Cross AI	Multi-domain synthesis — activated when 2+ domains match

How agents activate

1. Via Doc (chat-triggered) — Doc checks keyword lists and emits **CALL_AGENT**. Single-domain → specialist. Two or more domains → Cross AI runs matched agents in parallel threads and synthesizes.

2. Via agent direct chat — Users open an agent's tab; the server routes to POST /chat/agent/{agent_id}. Each agent maintains its own transcript separate from Doc.

3. Via crontab (scheduled) — agent_runner.py at 08:00 UTC daily. Per-user, per-agent, 20-hour debounce. Results land in the notification bell.

All agents are kind, helpful, and truthful — expert systems backed by scientific and medical LLMs. The Mental Wellness Guide provides the 988 crisis line for users expressing suicidal ideation.

System

GET /ping

Health check. No auth required.

GET /stats

Public. Returns total registered user count.

{"user_count": 23}

Authentication

POST /auth

Field	Type	Description
username	string	Required
password	string	Required (passphrase)
create_new	bool	Set true to register
hipaa_waiver_accepted	bool	Required when registering
profile	object	Optional initial profile on signup

POST /auth
{"username": "alice", "password": "mypassphrase"}

// Response
{"user_id": "user_alice", "username": "alice", "profile": {...}, "settings": {...}}

Chat

POST /chat

Send a message to Doc (primary coordinator). Doc may dispatch to a specialist agent internally. Pass user_id to persist profile updates.

Field	Type	Description
text	string	User's message
user_id	string	Optional — links to saved profile
session_id	string	Optional — pass back to continue session

POST /chat
{"text": "I have type 2 diabetes", "user_id": "user_alice", "session_id": "session_abc"}

// Response
{
  "response": "Thanks for sharing. How long have you had diabetes?",
  "session_id": "session_abc",
  "profile_updated": true,
  "profile": {"health_conditions": "type 2 diabetes", ...}
}

POST /chat/agent/{agent_id}

Chat directly with a named specialist agent. Each agent maintains its own transcript. Pass "init": true (or empty text) to trigger the agent's welcome message and begin onboarding.

Field	Type	Description
text	string	User's message. Empty or omitted → triggers intro.
user_id	string	Optional — for profile persistence
session_id	string	Optional session token
init	bool	Set true to request welcome message without saving a user turn

// First visit — trigger intro
POST /chat/agent/sleep
{"user_id": "user_alice", "init": true}

// Response
{
  "response": "Hi, I'm your Sleep Coach! How many hours are you typically sleeping?",
  "agent_id": "sleep",
  "session_id": "...",
  "profile_updated": false
}

// Regular turn
POST /chat/agent/protect
{"text": "My father had a heart attack at 55", "user_id": "user_alice"}

// Response includes profile update for family_history

User & Profile

GET /user/{user_id}

Fetch a user's full record (passphrase excluded).

PUT /user/{user_id}

Partial update. Allowed top-level keys: username, settings, profile. Nested objects are merged.

PUT /user/user_alice
{"profile": {"weight": "165 lbs", "goals": "lose 20 lbs", "avatar": "🧑"}}

Core profile fields

Field	Description
primary_concern	Main health focus
health_conditions	Diagnoses, chronic conditions
medications	Current medications and supplements
allergies	Drug or food allergies
age	Age
weight	Weight
height	Height
location	City / region
diet_type	Diet style (e.g. keto, vegan, Mediterranean)
exercise_frequency	How often they exercise
exercise_type	Type of exercise
sleep_hours	Average nightly sleep
sleep_quality	Self-rated sleep quality
stress_level	Self-rated stress level
goals	Health goals
avatar	Emoji string or base64 data URL for profile picture
notes	Free-form notes

Agent-specific profile fields

Written by agents during onboarding and chat. Merged into the same profile object.

Field	Agent
diet_type, dietary_restrictions, nutrition_goals, food_allergies	🥗 Diet
fitness_goals, fitness_level, exercise_limitations, preferred_workout_time	💪 Exercise
immune_concerns, supplements, autoimmune_conditions, family_history, smoking_status, last_checkup, screenings_due	🛡️ Protect AI
sleep_issues, bedtime, wake_time, sleep_aids, sleep_disorders	😴 Sleep
mental_health_concerns, therapy_status, coping_strategies, mindfulness_practice	🧠 Mind
relationship_status, social_support, loneliness_level, relationship_goals	💞 Relationships
living_environment, environmental_concerns, workplace_setup, climate_region	🌍 Environment

Settings

GET /settings/{user_id}

Get user settings.

PUT /settings/{user_id}

Partial update — only provided fields change.

Field	Values	Description
doc_style	questioning · professional · friendly	Doc's conversational tone
notifications_enabled	true · false	All notifications on/off
agent_subscriptions	array of agent IDs	Which agents send periodic check-ins and get chat tabs
agent_prefs	object	Per-agent preference overrides, e.g. `{"sleep": {"goal_hours": 8}}`
custom_agent_prompt	string (max 2000)	System prompt for the Custom agent

Agents

Manage agent subscriptions. Subscribed agents generate daily notifications via cron and appear as chat tabs in the UI. First activation triggers a 3-turn onboarding interview that fills domain-specific profile fields.

GET /agents/{user_id}

Get subscriptions and full agent list. Legacy agent IDs (immunity, disease_prevention) are transparently migrated to protect.

GET /agents/user_alice

{
  "subscriptions": ["diet", "sleep", "protect"],
  "agent_prefs": {},
  "available_agents": [
    {"id": "diet",         "name": "Diet",         "emoji": "🥗", "subscribed": true},
    {"id": "exercise",     "name": "Exercise",      "emoji": "💪", "subscribed": false},
    {"id": "protect",      "name": "Protect AI",    "emoji": "🛡️", "subscribed": true},
    {"id": "sleep",        "name": "Sleep",         "emoji": "😴", "subscribed": true},
    {"id": "mental_health","name": "Mind",          "emoji": "🧠", "subscribed": false},
    {"id": "relationships","name": "Relationships", "emoji": "💞", "subscribed": false},
    {"id": "environment",  "name": "Environment",   "emoji": "🌍", "subscribed": false},
    {"id": "custom",       "name": "Custom",        "emoji": "⚙️", "subscribed": false},
    {"id": "cross_ai",     "name": "Cross AI",      "emoji": "🔀", "subscribed": false}
  ]
}

PUT /agents/{user_id}

Update subscriptions, per-agent preferences, and custom agent prompt.

Field	Type	Description
subscriptions	string[]	Agent IDs. Unrecognized IDs silently dropped.
agent_prefs	object	Per-agent preferences (merged with existing)
custom_agent_prompt	string	System prompt for the Custom agent (max 2000 chars)

PUT /agents/user_alice
{
  "subscriptions": ["diet", "sleep", "protect"],
  "custom_agent_prompt": "You are a longevity coach focused on Blue Zone habits."
}

Cron runner: agent_runner.py — 08:00 UTC daily, 20-hour debounce per user per agent. Logs to /var/log/greendial_agents.log. Manual run:
python3 agent_runner.py --agent protect --user user_alice --dry-run

Conversations

GET /conversations/{user_id}/agents

Fetch all transcripts — Doc's and each agent's — in one call. Used by the browser on login.

GET /conversations/user_alice/agents

{
  "doc_transcript": "[2026-06-04T10:00:00] User: hi\n[2026-06-04T10:00:01] Doc: ...",
  "agents": {
    "sleep": "[2026-06-04T08:00:00] Sleep: Hi, I'm your Sleep Coach! ...",
    "diet":  ""
  }
}

GET /conversations/{user_id}

Get Doc's transcript only (legacy endpoint, backward-compatible).

DELETE /conversations/{user_id}

Clear Doc's transcript.

DELETE /conversations/{user_id}/agent/{agent_id}

Clear one agent's transcript without affecting others.

Notifications

GET /notifications/{user_id}

List pending notifications (last 10). Notifications come from Doc, agents, and the cron runner.

POST /notifications/{user_id}/generate

Trigger an on-demand notification based on the user's current profile.

DELETE /notifications/{user_id}/{notification_id}

Dismiss a notification.

Third-Party API Basic Auth

Use Authorization: Basic <base64(username:passphrase)> for machine-to-machine profile sync.

GET /api/v1/profile

Read the authenticated user's health profile.

PUT /api/v1/profile

Merge profile fields from an external app (wearable, EHR export, etc.).

PUT /api/v1/profile
Authorization: Basic YWxpY2U6bXlwYXNzcGhyYXNl

{"profile": {"weight": "162 lbs", "steps_per_day": "8200"}}

Spec Files

Machine-readable specs for tooling, code generation, and AI agents that interact with this API.

File	URL	Format
OpenAPI 3.1	/spec/openapi.yaml	Full endpoint schemas, request/response models
Arazzo 1.0	/spec/arazzo.yaml	Workflow descriptions: chat dispatch, cron notifications, onboarding, profile updates

How Doc Works

Doc is the primary coordinator. Its prompt is assembled dynamically each turn from profile state, conversation stage, and optional agent context.

Two structured markers are stripped server-side before returning text to the user:
• **PROFILE_UPDATE** {"field": "value"} — persists health data
• **CALL_AGENT** {"agent": "sleep"} — triggers a specialist sub-call

Dispatch flow

User message
  │
  ├─ keyword match → 0 agents  →  Doc answers directly
  │
  ├─ keyword match → 1 agent   →  specialist runs → Doc synthesizes with context
  │
  └─ keyword match → 2+ agents →  Cross AI runs matched agents in parallel threads
                                   → Cross AI synthesizes → Doc wraps final reply

Profile updates extracted from any response → saved to S3 → sidebar refreshes

Language mirroring

All agents (Doc and specialists) detect message length and tone from each user turn and inject a style-matching instruction. Very short messages get terse replies; detailed messages get thorough ones. Casual phrasing gets casual responses.

Profile update syntax

// Set a field **PROFILE_UPDATE** {"age": "44", "health_conditions": "type 2 diabetes"} // Append to existing value **PROFILE_UPDATE** {"medications": "+metformin 500mg twice daily"} // Delete a field **PROFILE_UPDATE** {"allergies": null} // Nested sub-object **PROFILE_UPDATE** {"vitals": {"bp": "120/80", "resting_hr": "62"}}

GreenDial is open source. Questions? mickeyshaughnessy@gmail.com