CareVoice LogoPATH by CareVoiceOS

Developer

API documentation and developer resources

APIs
API documentation and endpoints
Webhooks
Real-time event notifications (Under Development)
POST/api/playground/chat

AI-powered health assessment chat endpoint

Auth Required
AI

Request

Required Fields:
  • message
  • session_id
Optional Fields:
  • attributes_to_attain
  • language
Example Request:
{
  "message": "I'm 25 years old and exercise 3 times a week",
  "session_id": "uuid-string",
  "attributes_to_attain": [
    {
      "key": "age",
      "name": "Age",
      "description": "User's age in years",
      "metric_name": "age",
      "data_type": "integer"
    }
  ],
  "language": "en"
}

Response

Success Response:
200 OK
{
  "success": true,
  "response_message": "Great! I've recorded your age as 25 and exercise frequency as 3 times per week.",
  "extracted_attributes": [
    {
      "name": "age",
      "value": 25,
      "confidence": 0.95,
      "source": "chat",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ],
  "assessment_phase_complete": false,
  "current_phase": "assessment_phase",
  "risk_factors": [],
  "recommendations": [],
  "wellness_summary": "Active lifestyle with regular exercise"
}
Error Response:
400/401/500 Error
{
  "success": false,
  "error": "Authentication required"
}
POST/api/playground/suggest-attribute

Get AI-suggested attributes for collection

Auth Required
AI

Request

Required Fields:
  • collected_attributes
Optional Fields:
  • language
Example Request:
{
  "collected_attributes": [
    {
      "name": "age",
      "value": 25,
      "confidence": 0.95,
      "source": "chat",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ],
  "language": "en"
}

Response

Success Response:
200 OK
{
  "success": true,
  "suggested_attributes": [
    {
      "key": "height",
      "name": "Height",
      "description": "User's height in centimeters",
      "metric_name": "height",
      "data_type": "integer"
    }
  ]
}
Error Response:
400/401/500 Error
{
  "success": false,
  "error": "Failed to generate suggestions"
}
POST/api/profiling

Generate comprehensive health profile from conversation history

Auth Required
AI

Request

Required Fields:
  • sessionId
Optional Fields:
  • conversationHistory
  • collectedAttributes
  • availableTasks
  • attributesToAttain
  • language
  • currentProfile
  • casualMode
Example Request:
{
  "sessionId": "uuid-string",
  "conversationHistory": [
    {
      "type": "user",
      "content": "I'm 25 years old and exercise 3 times a week",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "type": "ai",
      "content": "Great! I've recorded your age as 25 and exercise frequency as 3 times per week.",
      "timestamp": "2024-01-15T10:30:05Z"
    }
  ],
  "collectedAttributes": [
    {
      "attribute_name": "profile_age_years_static",
      "display_name": "Age",
      "value": 25,
      "confidence": 0.95,
      "source": "chat",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ],
  "availableTasks": [
    {
      "key": "daily_step_goal_setting",
      "display_name": "Daily Step Goal Setting",
      "annotation": "Set and track daily step goals"
    }
  ],
  "attributesToAttain": [
    {
      "attribute_name": "profile_height_cm_static",
      "display_name": "Height",
      "description": "User's height in centimeters",
      "metric_name": "height",
      "data_type": "integer",
      "collection_method": "user",
      "category_name": "demographics",
      "pillar_name": "physical"
    }
  ],
  "language": "en",
  "casualMode": false
}

Response

Success Response:
200 OK
{
  "success": true,
  "data": {
    "profileMessage": "Based on our conversation, you're a 25-year-old with an active lifestyle. You exercise 3 times per week, which is excellent for your health. Your current profile shows good physical activity habits.",
    "extractedAttributes": [
      {
        "attribute_name": "profile_activity_level_static",
        "display_name": "Activity Level",
        "value": 3,
        "confidence": 0.9,
        "source": "chat",
        "timestamp": "2024-01-15T10:30:00Z"
      }
    ],
    "summary": "Active lifestyle with regular exercise. Good physical health indicators based on exercise frequency.",
    "assessmentPhaseComplete": false,
    "currentPhase": "assessment_phase",
    "riskFactors": [],
    "recommendations": [
      "Continue maintaining your current exercise routine",
      "Consider adding variety to your workouts"
    ],
    "tasksRecommended": [
      {
        "key": "weekly_progress_review",
        "display_name": "Weekly Progress Review",
        "annotation": "Review your weekly exercise progress"
      }
    ]
  }
}
Error Response:
400/401/500 Error
{
  "success": false,
  "error": "Failed to generate profiling response"
}
POST/api/segment/match

Match user attributes against health segments

Auth Required
Segments

Request

Required Fields:
  • attributes
Example Request:
{
  "attributes": [
    {
      "name": "age",
      "value": 25,
      "confidence": 0.95,
      "source": "chat",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "name": "exercise_frequency",
      "value": 3,
      "confidence": 0.9,
      "source": "chat",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ]
}

Response

Success Response:
200 OK
{
  "success": true,
  "matched_segments": [
    {
      "id": "uuid-string",
      "name": "Active Young Adults",
      "description": "Young adults with regular exercise habits",
      "matchScore": 0.85,
      "matchReasoning": "Age 25 and exercise frequency 3x/week matches criteria",
      "categoryId": "uuid-string"
    }
  ]
}
Error Response:
400/401/500 Error
{
  "success": false,
  "error": "Invalid attributes format"
}
POST/api/segment/recommendation

Get AI recommendations for matched segments

Auth Required
Segments

Request

Required Fields:
  • segment_id
  • user_attributes
Optional Fields:
  • language
Example Request:
{
  "segment_id": "uuid-string",
  "user_attributes": [
    {
      "name": "age",
      "value": 25,
      "confidence": 0.95,
      "source": "chat",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ],
  "language": "en"
}

Response

Success Response:
200 OK
{
  "success": true,
  "recommendations": [
    {
      "id": "uuid-string",
      "title": "Increase Cardio Exercise",
      "description": "Consider adding 30 minutes of cardio 2x per week",
      "priority": "medium",
      "category": "exercise"
    }
  ]
}
Error Response:
400/401/500 Error
{
  "success": false,
  "error": "Segment not found"
}
POST/api/segment/predict

Predict segment membership based on user attribute values with AI-powered confidence scoring

Auth Required
Segments

Request

Required Fields:
  • attributes
Example Request:
{
  "attributes": [
    {
      "attribute_id": "uuid-string",
      "attribute_name": "phy_steps_count_daily",
      "attribute_display_name": "Daily Steps",
      "attribute_data": {
        "id": "uuid-string",
        "name": "phy_steps_count_daily",
        "display_name": "Daily Steps",
        "description": "Number of steps taken per day",
        "wellness_pillars": {
          "display_name": "Physical Health",
          "description": "Physical wellness indicators"
        },
        "attribute_categories": {
          "display_name": "Activity",
          "description": "Physical activity metrics"
        },
        "data_type_id": "uuid-string",
        "validation_rules": {
          "min": 0,
          "max": 50000
        },
        "allowed_values": null
      },
      "value": 8500
    },
    {
      "attribute_id": "uuid-string-2",
      "attribute_name": "men_sleep_hours_daily",
      "attribute_display_name": "Sleep Hours",
      "attribute_data": {
        "id": "uuid-string-2",
        "name": "men_sleep_hours_daily",
        "display_name": "Sleep Hours",
        "description": "Hours of sleep per night",
        "wellness_pillars": {
          "display_name": "Mental Health",
          "description": "Mental wellness indicators"
        },
        "attribute_categories": {
          "display_name": "Sleep",
          "description": "Sleep quality metrics"
        },
        "data_type_id": "uuid-string",
        "validation_rules": {
          "min": 0,
          "max": 24
        },
        "allowed_values": null
      },
      "value": 6
    }
  ]
}

Response

Success Response:
200 OK
{
  "success": true,
  "predictions": [
    {
      "segment_id": "uuid-string",
      "segment_name": "active_lifestyle",
      "segment_display_name": "Active Lifestyle",
      "confidence": 85,
      "reasoning": "User's daily steps (8500) align well with segment rules requiring 8000+ steps. Partial match on sleep hours."
    },
    {
      "segment_id": "uuid-string-2",
      "segment_name": "sleep_deprived",
      "segment_display_name": "Sleep Deprived",
      "confidence": 72,
      "reasoning": "Sleep hours (6) fall within the segment's criteria for insufficient sleep (<7 hours). Moderate confidence due to single attribute match."
    }
  ]
}
Error Response:
400/401/500 Error
{
  "success": false,
  "error": "Authentication required"
}
GET/api/attributes/keys

Get specific attributes by their keys (names) with full metadata

Auth Required
Data

Request

Required Fields:
  • keys (query parameter)
Optional Fields:
  • limit (query parameter, default: 50, max: 100)
Example Request:
{
  "query": {
    "keys": "phy_steps_count_daily,men_sleep_hours_daily,profile_age_years_static",
    "limit": 50
  },
  "alternative_format": {
    "keys": "[\"phy_steps_count_daily\",\"men_sleep_hours_daily\"]"
  }
}

Response

Success Response:
200 OK
{
  "success": true,
  "data": [
    {
      "id": "uuid-string",
      "name": "phy_steps_count_daily",
      "display_name": "Daily Steps",
      "description": "Number of steps taken per day",
      "pillar_id": "uuid-string",
      "attribute_category_id": "uuid-string",
      "data_type_id": "uuid-string",
      "sensitivity_id": "uuid-string",
      "metric_name": "steps_count",
      "reset_frequency": "daily",
      "collection_method": "integrated",
      "data_source": "Apple Health",
      "is_required": false,
      "is_active": true,
      "validation_rules": {
        "min": 0,
        "max": 50000
      },
      "default_value": null,
      "allowed_values": null,
      "wellness_pillars": {
        "id": "uuid-string",
        "name": "physical",
        "display_name": "Physical Health",
        "description": "Physical wellness indicators"
      },
      "attribute_categories": {
        "id": "uuid-string",
        "name": "activity",
        "display_name": "Activity",
        "description": "Physical activity metrics"
      },
      "attribute_data_types": {
        "id": "uuid-string",
        "name": "integer",
        "display_name": "Integer"
      },
      "data_sensitivity_levels": {
        "id": "uuid-string",
        "name": "low",
        "display_name": "Low"
      }
    }
  ],
  "count": 1
}
Error Response:
400/401/500 Error
{
  "success": false,
  "error": "Missing required parameter: keys",
  "data": []
}
GET/api/playground/categories

Get available attribute categories

Auth Required
AI

Request

Example Request:
{}

Response

Success Response:
200 OK
{
  "success": true,
  "categories": [
    {
      "id": "uuid-string",
      "name": "demographics",
      "display_name": "Demographics",
      "description": "Basic demographic information"
    }
  ]
}
Error Response:
400/401/500 Error
{
  "success": false,
  "error": "Failed to fetch categories"
}
GET/api/segment/categories

Get available segment categories

Auth Required
Segments

Request

Example Request:
{}

Response

Success Response:
200 OK
{
  "success": true,
  "categories": [
    {
      "id": "uuid-string",
      "name": "lifestyle",
      "display_name": "Lifestyle",
      "description": "Lifestyle-related health segments"
    }
  ]
}
Error Response:
400/401/500 Error
{
  "success": false,
  "error": "Failed to fetch categories"
}
POST/api/invitation/verify

Verify invitation code for user registration

Authentication

Request

Required Fields:
  • invitationCode
Example Request:
{
  "invitationCode": "shanedi"
}

Response

Success Response:
200 OK
{
  "success": true,
  "message": "Invitation code is valid"
}
Error Response:
400/401/500 Error
{
  "success": false,
  "error": "Invalid invitation code"
}
POST/api/avatar/upload

Upload user avatar image

Auth Required
Media

Request

Required Fields:
  • file
Example Request:
{
  "file": "FormData with image file"
}

Response

Success Response:
200 OK
{
  "success": true,
  "url": "https://storage.example.com/avatars/user-uuid.jpg"
}
Error Response:
400/401/500 Error
{
  "success": false,
  "error": "File upload failed"
}
GET/api/behavior/journeys

List all journeys with pagination and filtering

Auth Required
Behavior

Request

Required Fields:
  • Authorization (header): Bearer token for authentication
Optional Fields:
  • page (number): Page number for pagination (default: 1)
  • limit (number): Number of items per page (default: 10, max: 100)
  • search (string): Search journeys by name
  • is_active (boolean): Filter by active status (true/false)
  • include_inactive (boolean): Include inactive journeys (default: false)
Example Request:
{
  "headers": {
    "Authorization": "Bearer your-jwt-token"
  },
  "query": {
    "page": 1,
    "limit": 10,
    "search": "step tracking",
    "is_active": true,
    "include_inactive": false
  }
}

Response

Success Response:
200 OK
{
  "data": [
    {
      "id": "uuid-string",
      "name": "Step Tracking Journey",
      "description": "Track daily steps using Apple Health integration",
      "icon_image_url": "https://example.com/icon.svg",
      "annotation": "AI-powered step tracking with health insights",
      "sdk_info": {
        "provider": "Apple Health",
        "version": "1.0",
        "capabilities": [
          "steps",
          "distance"
        ]
      },
      "entry_point": "User opens app and navigates to health tracking",
      "exit_point": "User receives daily step summary and weekly progress report",
      "user_flow_description": "1. User opens app → 2. Selects step tracking → 3. Connects Apple Health → 4. Views daily steps → 5. Receives insights → 6. Gets weekly report",
      "required_attributes": [
        {
          "key": "phy_steps_count_daily",
          "name": "Daily Step Count"
        }
      ],
      "tasks": [
        {
          "key": "daily_step_goal_setting",
          "order": 1,
          "required": true
        },
        {
          "key": "weekly_progress_review",
          "order": 2,
          "required": false
        }
      ],
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "created_by": "user-uuid",
      "updated_by": "user-uuid"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPrevPage": false,
    "nextPage": 2,
    "prevPage": null
  },
  "filters": {
    "search": "step tracking",
    "is_active": true,
    "include_inactive": false
  }
}
Error Response:
400/401/500 Error
{
  "success": false,
  "error": "Authentication required"
}

Authentication

Most API endpoints require authentication using a Bearer token in the Authorization header.

Header Format:

Authorization: Bearer your-api-token-here

You can generate API tokens in the API Keys settings.