Goals API
The Goals API enables goal tracking with AI-generated roadmaps, progress tracking, and milestone management.
Goal Object
Goal description (optional)
Target completion date (ISO 8601)
AI-generated roadmap with nodes and edges
Completion percentage (0-100)
Goal status: active, completed, abandoned
Endpoints
Create Goal
Create a new goal.
{
"title": "Learn Machine Learning",
"description": "Master ML fundamentals and build 3 projects",
"target_date": "2026-12-31T00:00:00Z"
}
{
"id": "goal_123",
"title": "Learn Machine Learning",
"description": "Master ML fundamentals and build 3 projects",
"target_date": "2026-12-31T00:00:00Z",
"roadmap": null,
"progress": 0,
"status": "active",
"created_at": "2026-02-19T10:00:00Z",
"updated_at": "2026-02-19T10:00:00Z"
}
List Goals
Get all goals for the current user.
[
{
"id": "goal_123",
"title": "Learn Machine Learning",
"description": "Master ML fundamentals",
"target_date": "2026-12-31T00:00:00Z",
"progress": 25,
"status": "active",
"created_at": "2026-02-19T10:00:00Z"
}
]
Get Goal
Get a specific goal with roadmap.
GET /api/v1/goals/{goal_id}
{
"id": "goal_123",
"title": "Learn Machine Learning",
"roadmap": {
"nodes": [
{
"id": "node_1",
"label": "Complete Python basics",
"completed": true,
"position": {"x": 100, "y": 100}
},
{
"id": "node_2",
"label": "Study linear algebra",
"completed": false,
"position": {"x": 200, "y": 100}
}
],
"edges": [
{
"id": "edge_1",
"source": "node_1",
"target": "node_2"
}
]
},
"progress": 25
}
Delete Goal
Delete a goal.
DELETE /api/v1/goals/{goal_id}
Roadmap Management
Generate Roadmap (WebSocket)
Generate AI roadmap via WebSocket for real-time streaming.
const ws = new WebSocket('wss://api.heygaia.io/api/v1/ws/roadmap');
ws.onopen = () => {
ws.send(JSON.stringify({
goal_id: 'goal_123',
goal_title: 'Learn Machine Learning'
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.status) {
console.log('Progress:', data.status);
}
if (data.roadmap) {
console.log('Roadmap generated:', data.roadmap);
}
if (data.success) {
console.log('Goal updated successfully');
ws.close();
}
};
Update Node Status
Mark a roadmap node as completed.
PATCH /api/v1/goals/{goal_id}/roadmap/nodes/{node_id}
{
"id": "goal_123",
"progress": 50,
"roadmap": {
"nodes": [...]
}
}
Progress Tracking
Progress is automatically calculated based on completed roadmap nodes:
- Each node contributes equally to overall progress
- Completing a node updates the goal’s progress percentage
- Progress syncs with linked todos if applicable
Todo Integration
Goals can be linked to todos for task management:
- Roadmap nodes can be converted to todos
- Todo completion syncs with goal progress
- Subtasks map to roadmap milestones
Next Steps
Memory API
Store contextual memories
Integrations
Connect third-party services