system/docs/api.md

# Personal System API Documentation

## Overview

This API serves a personal productivity system with habit tracking and intake metrics. The system supports three client types:
- **TUI (Terminal User Interface)**: Command-line interface for quick interactions
- **Mobile App**: Native mobile application for on-the-go tracking
- **Web Application**: Rich web interface with analytics and reporting

## Base URL

```
Production: https://api.personal-system.com/v1
Development: http://localhost:3000/api/v1
```

## Authentication

All endpoints require authentication via JWT tokens passed in the Authorization header:

```
Authorization: Bearer <jwt_token>
```

### Authentication Endpoints

#### Login
```http
POST /auth/login
```

**Request Body:**
```json
{
  "email": "user@example.com",
  "password": "securepassword"
}
```

**Response:**
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-uuid",
    "username": "johndoe",
    "email": "user@example.com"
  },
  "expires_at": "2024-01-15T12:00:00Z"
}
```

#### Refresh Token
```http
POST /auth/refresh
```

**Request Body:**
```json
{
  "refresh_token": "refresh_token_here"
}
```

#### Logout
```http
POST /auth/logout
```

## Common Patterns

### Pagination
List endpoints support pagination with the following parameters:
- `limit`: Number of items per page (default: 50, max: 100)
- `offset`: Number of items to skip (default: 0)
- `cursor`: Cursor-based pagination for real-time data

**Example:**
```http
GET /api/habits?limit=20&offset=40
```

### Filtering
Most endpoints support filtering via query parameters:
- `fields`: Select specific fields to return
- `active`: Filter by active status (true/false)
- `start_date`: Filter by start date (ISO 8601)
- `end_date`: Filter by end date (ISO 8601)

**Example:**
```http
GET /api/habits?fields=id,name,active&active=true
```

### Response Format
All responses follow this structure:
```json
{
  "data": [], // or {} for single items
  "meta": {
    "total": 100,
    "limit": 20,
    "offset": 40,
    "has_more": true
  },
  "links": {
    "self": "/api/habits?limit=20&offset=40",
    "next": "/api/habits?limit=20&offset=60",
    "prev": "/api/habits?limit=20&offset=20"
  }
}
```

## Error Handling

### Error Response Format
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "target_count",
        "message": "Must be a positive integer"
      }
    ],
    "request_id": "req-uuid"
  }
}
```

### HTTP Status Codes
- `200 OK`: Success
- `201 Created`: Resource created successfully
- `400 Bad Request`: Invalid request parameters
- `401 Unauthorized`: Authentication required
- `403 Forbidden`: Insufficient permissions
- `404 Not Found`: Resource not found
- `409 Conflict`: Resource already exists
- `422 Unprocessable Entity`: Validation error
- `429 Too Many Requests`: Rate limit exceeded
- `500 Internal Server Error`: Server error

## Rate Limiting

Rate limits are enforced per client type:
- **TUI**: 100 requests per minute
- **Mobile**: 200 requests per minute
- **Web**: 300 requests per minute

Rate limit headers are included in all responses:
```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642262400
```

## Caching

### ETags
Most GET endpoints support ETags for efficient caching:
```http
ETag: "33a64df551"
```

Use the `If-None-Match` header to check for updates:
```http
If-None-Match: "33a64df551"
```

### Cache Headers
```http
Cache-Control: max-age=300, private
Last-Modified: Mon, 15 Jan 2024 10:00:00 GMT
```

---

# Habits API

## Core Endpoints

### List Habits
```http
GET /api/habits
```

**Query Parameters:**
- `active`: Filter by active status (true/false)
- `frequency_type`: Filter by frequency type (daily/interval/multi_daily)
- `fields`: Select specific fields
- `limit`, `offset`: Pagination

**Response:**
```json
{
  "data": [
    {
      "id": "habit-uuid",
      "name": "Take vitamins",
      "description": "Daily vitamin supplement",
      "frequency_type": "daily",
      "target_count": 1,
      "interval_days": null,
      "active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "total": 5,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}
```

### Get Habit
```http
GET /api/habits/{habit_id}
```

**Response:**
```json
{
  "data": {
    "id": "habit-uuid",
    "name": "Take vitamins",
    "description": "Daily vitamin supplement",
    "frequency_type": "daily",
    "target_count": 1,
    "interval_days": null,
    "active": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

### Create Habit
```http
POST /api/habits
```

**Request Body:**
```json
{
  "name": "Morning meditation",
  "description": "15 minutes of mindfulness",
  "frequency_type": "daily",
  "target_count": 1
}
```

**Response:** `201 Created` with the created habit object.

### Update Habit
```http
PUT /api/habits/{habit_id}
```

**Request Body:**
```json
{
  "name": "Updated habit name",
  "description": "Updated description",
  "active": false
}
```

### Delete Habit
```http
DELETE /api/habits/{habit_id}
```

**Response:** `204 No Content`

## Habit Completions

### List Completions
```http
GET /api/habits/{habit_id}/completions
```

**Query Parameters:**
- `start_date`: ISO 8601 date
- `end_date`: ISO 8601 date
- `limit`, `offset`: Pagination

**Response:**
```json
{
  "data": [
    {
      "id": "completion-uuid",
      "habit_id": "habit-uuid",
      "completed_at": "2024-01-15T08:30:00Z",
      "notes": "Completed during lunch break",
      "created_at": "2024-01-15T08:30:00Z"
    }
  ],
  "meta": {
    "total": 30,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}
```

### Create Completion
```http
POST /api/habits/{habit_id}/completions
```

**Request Body:**
```json
{
  "completed_at": "2024-01-15T08:30:00Z",
  "notes": "Completed during lunch break"
}
```

**Response:** `201 Created` with the completion object.

### Bulk Create Completions
```http
POST /api/habits/completions/bulk
```

**Request Body:**
```json
{
  "completions": [
    {
      "habit_id": "habit-uuid-1",
      "completed_at": "2024-01-15T08:30:00Z",
      "notes": "Morning habit"
    },
    {
      "habit_id": "habit-uuid-2",
      "completed_at": "2024-01-15T09:00:00Z"
    }
  ]
}
```

## Habit Status

### Get Habit Status
```http
GET /api/habits/{habit_id}/status
```

**Response:**
```json
{
  "data": {
    "habit_id": "habit-uuid",
    "completed_today": true,
    "completions_today": 2,
    "target_count": 2,
    "completion_rate": 1.0,
    "current_streak": 15,
    "longest_streak": 30,
    "next_due_date": null,
    "last_completed_at": "2024-01-15T08:30:00Z",
    "status": "completed"
  }
}
```

### Get All Habits Status
```http
GET /api/habits/status
```

**Response:**
```json
{
  "data": [
    {
      "habit_id": "habit-uuid",
      "name": "Take vitamins",
      "completed_today": true,
      "completions_today": 1,
      "target_count": 1,
      "status": "completed"
    }
  ]
}
```

### Bulk Status Check
```http
POST /api/habits/status/bulk
```

**Request Body:**
```json
{
  "habit_ids": ["habit-uuid-1", "habit-uuid-2"]
}
```

## Habit Analytics

### Get Habit Statistics
```http
GET /api/habits/{habit_id}/stats
```

**Query Parameters:**
- `period`: week/month/year (default: month)
- `start_date`: ISO 8601 date
- `end_date`: ISO 8601 date

**Response:**
```json
{
  "data": {
    "habit_id": "habit-uuid",
    "period": "month",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "total_completions": 28,
    "total_days": 31,
    "completion_rate": 0.9032,
    "current_streak": 15,
    "longest_streak": 20,
    "average_completions_per_day": 1.2,
    "daily_breakdown": [
      {
        "date": "2024-01-01",
        "completions": 1,
        "target_met": true
      }
    ]
  }
}
```

### Get Habit Calendar
```http
GET /api/habits/calendar
```

**Query Parameters:**
- `start_date`: ISO 8601 date
- `end_date`: ISO 8601 date
- `habit_ids`: Comma-separated list of habit IDs

**Response:**
```json
{
  "data": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "habits": [
      {
        "habit_id": "habit-uuid",
        "name": "Take vitamins",
        "calendar_data": [
          {
            "date": "2024-01-01",
            "completions": 1,
            "target_met": true,
            "status": "completed"
          }
        ]
      }
    ]
  }
}
```

### Get Dashboard
```http
GET /api/habits/dashboard
```

**Response:**
```json
{
  "data": {
    "overview": {
      "total_habits": 5,
      "active_habits": 4,
      "completed_today": 3,
      "completion_rate_today": 0.75,
      "current_streak_avg": 12.5
    },
    "habits": [
      {
        "habit_id": "habit-uuid",
        "name": "Take vitamins",
        "frequency_type": "daily",
        "completed_today": true,
        "completions_today": 1,
        "target_count": 1,
        "current_streak": 15,
        "status": "completed"
      }
    ],
    "upcoming": [
      {
        "habit_id": "habit-uuid",
        "name": "Weekly cleaning",
        "next_due_date": "2024-01-20",
        "days_until_due": 3
      }
    ]
  }
}
```

---

# Intake Tracker API

## Intake Metrics

### List Intake Metrics
```http
GET /api/intake/metrics
```

**Query Parameters:**
- `active`: Filter by active status (true/false)
- `is_cumulative`: Filter by cumulative type (true/false)
- `fields`: Select specific fields

**Response:**
```json
{
  "data": [
    {
      "id": "metric-uuid",
      "metric_type": "water",
      "unit": "ml",
      "display_name": "Water Intake",
      "target_value": 2000,
      "min_value": null,
      "max_value": null,
      "is_cumulative": true,
      "active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "total": 3,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}
```

### Get Intake Metric
```http
GET /api/intake/metrics/{metric_id}
```

### Create Intake Metric
```http
POST /api/intake/metrics
```

**Request Body:**
```json
{
  "metric_type": "water",
  "unit": "ml",
  "display_name": "Water Intake",
  "target_value": 2000,
  "is_cumulative": true
}
```

### Update Intake Metric
```http
PUT /api/intake/metrics/{metric_id}
```

### Delete Intake Metric
```http
DELETE /api/intake/metrics/{metric_id}
```

## Intake Records

### List Intake Records
```http
GET /api/intake/metrics/{metric_id}/records
```

**Query Parameters:**
- `start_date`: ISO 8601 date
- `end_date`: ISO 8601 date
- `limit`, `offset`: Pagination

**Response:**
```json
{
  "data": [
    {
      "id": "record-uuid",
      "intake_metric_id": "metric-uuid",
      "value": 500,
      "recorded_at": "2024-01-15T08:30:00Z",
      "notes": "Morning hydration",
      "created_at": "2024-01-15T08:30:00Z"
    }
  ],
  "meta": {
    "total": 8,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}
```

### Create Intake Record
```http
POST /api/intake/metrics/{metric_id}/records
```

**Request Body:**
```json
{
  "value": 500,
  "recorded_at": "2024-01-15T08:30:00Z",
  "notes": "Morning hydration"
}
```

### Bulk Create Records
```http
POST /api/intake/records/bulk
```

**Request Body:**
```json
{
  "records": [
    {
      "intake_metric_id": "metric-uuid-1",
      "value": 500,
      "recorded_at": "2024-01-15T08:30:00Z",
      "notes": "Morning water"
    },
    {
      "intake_metric_id": "metric-uuid-2",
      "value": 70.5,
      "recorded_at": "2024-01-15T07:00:00Z"
    }
  ]
}
```

## Intake Progress

### Get Metric Progress
```http
GET /api/intake/metrics/{metric_id}/progress
```

**Query Parameters:**
- `date`: Specific date (default: today)

**Response:**
```json
{
  "data": {
    "metric_id": "metric-uuid",
    "date": "2024-01-15",
    "current_value": 1500,
    "target_value": 2000,
    "unit": "ml",
    "percentage_complete": 75,
    "status": "in_progress",
    "remaining": 500,
    "entries_count": 3,
    "first_entry_at": "2024-01-15T07:00:00Z",
    "last_entry_at": "2024-01-15T14:30:00Z"
  }
}
```

### Get All Metrics Progress
```http
GET /api/intake/progress
```

**Response:**
```json
{
  "data": [
    {
      "metric_id": "metric-uuid",
      "metric_type": "water",
      "display_name": "Water Intake",
      "current_value": 1500,
      "target_value": 2000,
      "unit": "ml",
      "percentage_complete": 75,
      "status": "in_progress"
    }
  ]
}
```

## Intake Analytics

### Get Daily Summaries
```http
GET /api/intake/metrics/{metric_id}/summaries
```

**Query Parameters:**
- `start_date`: ISO 8601 date
- `end_date`: ISO 8601 date
- `period`: day/week/month (default: day)

**Response:**
```json
{
  "data": [
    {
      "id": "summary-uuid",
      "intake_metric_id": "metric-uuid",
      "date": "2024-01-15",
      "total_value": 2100,
      "entry_count": 4,
      "first_entry_at": "2024-01-15T07:00:00Z",
      "last_entry_at": "2024-01-15T20:00:00Z",
      "target_met": true,
      "target_value": 2000
    }
  ]
}
```

### Get Intake Trends
```http
GET /api/intake/metrics/{metric_id}/trends
```

**Query Parameters:**
- `period`: week/month/year (default: month)
- `start_date`: ISO 8601 date
- `end_date`: ISO 8601 date

**Response:**
```json
{
  "data": {
    "metric_id": "metric-uuid",
    "period": "month",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "average_daily_value": 1850,
    "target_value": 2000,
    "target_achievement_rate": 0.85,
    "highest_value": 2500,
    "lowest_value": 1200,
    "total_entries": 124,
    "daily_data": [
      {
        "date": "2024-01-01",
        "value": 1800,
        "target_met": false,
        "entry_count": 4
      }
    ]
  }
}
```

### Get Intake Calendar
```http
GET /api/intake/calendar
```

**Query Parameters:**
- `start_date`: ISO 8601 date
- `end_date`: ISO 8601 date
- `metric_ids`: Comma-separated list of metric IDs

**Response:**
```json
{
  "data": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "metrics": [
      {
        "metric_id": "metric-uuid",
        "display_name": "Water Intake",
        "unit": "ml",
        "calendar_data": [
          {
            "date": "2024-01-01",
            "value": 1800,
            "target_value": 2000,
            "target_met": false,
            "entry_count": 4
          }
        ]
      }
    ]
  }
}
```

### Get Dashboard
```http
GET /api/intake/dashboard
```

**Response:**
```json
{
  "data": {
    "overview": {
      "total_metrics": 3,
      "active_metrics": 3,
      "targets_met_today": 2,
      "target_achievement_rate": 0.67
    },
    "metrics": [
      {
        "metric_id": "metric-uuid",
        "display_name": "Water Intake",
        "current_value": 1500,
        "target_value": 2000,
        "unit": "ml",
        "percentage_complete": 75,
        "status": "in_progress",
        "entries_today": 3
      }
    ]
  }
}
```

---

# Cross-System Integration

## Unified Dashboard
```http
GET /api/dashboard
```

**Response:**
```json
{
  "data": {
    "overview": {
      "date": "2024-01-15",
      "habits_completed": 3,
      "habits_total": 4,
      "intake_targets_met": 2,
      "intake_targets_total": 3
    },
    "habits": {
      "completed_today": 3,
      "completion_rate": 0.75,
      "current_streak_avg": 12.5,
      "habits": [
        {
          "habit_id": "habit-uuid",
          "name": "Take vitamins",
          "status": "completed",
          "completions_today": 1,
          "target_count": 1
        }
      ]
    },
    "intake": {
      "targets_met": 2,
      "target_achievement_rate": 0.67,
      "metrics": [
        {
          "metric_id": "metric-uuid",
          "display_name": "Water Intake",
          "current_value": 1500,
          "target_value": 2000,
          "status": "in_progress"
        }
      ]
    }
  }
}
```

## Goal Integration

### List Goal-Linked Habits
```http
GET /api/goals/habits
```

**Response:**
```json
{
  "data": [
    {
      "habit_id": "habit-uuid",
      "name": "Drink enough water",
      "goal_type": "water",
      "goal_target": 2000,
      "goal_unit": "ml",
      "linked_metric_id": "metric-uuid",
      "auto_complete": true,
      "status": "pending"
    }
  ]
}
```

### Get Goal Status
```http
GET /api/goals/status
```

**Response:**
```json
{
  "data": [
    {
      "habit_id": "habit-uuid",
      "name": "Drink enough water",
      "goal_target": 2000,
      "current_intake": 1500,
      "goal_progress": 0.75,
      "goal_met": false,
      "habit_completed": false,
      "can_auto_complete": false
    }
  ]
}
```

## Reports

### Weekly Report
```http
GET /api/reports/weekly
```

**Query Parameters:**
- `start_date`: ISO 8601 date (default: start of current week)

**Response:**
```json
{
  "data": {
    "period": "week",
    "start_date": "2024-01-08",
    "end_date": "2024-01-14",
    "habits": {
      "total_habits": 4,
      "average_completion_rate": 0.82,
      "best_habit": {
        "name": "Take vitamins",
        "completion_rate": 1.0
      },
      "needs_attention": [
        {
          "name": "Exercise",
          "completion_rate": 0.57
        }
      ]
    },
    "intake": {
      "total_metrics": 3,
      "average_target_achievement": 0.75,
      "best_metric": {
        "display_name": "Water Intake",
        "achievement_rate": 0.86
      }
    }
  }
}
```

### Monthly Report
```http
GET /api/reports/monthly
```

---

# Real-Time Features

## WebSocket Connection

### Connect to WebSocket
```
wss://api.personal-system.com/v1/ws?token=<jwt_token>
```

### WebSocket Events

#### Subscribe to Events
```json
{
  "type": "subscribe",
  "channels": ["habits", "intake", "dashboard"]
}
```

#### Habit Completion Event
```json
{
  "type": "habit_completed",
  "data": {
    "habit_id": "habit-uuid",
    "completion_id": "completion-uuid",
    "completed_at": "2024-01-15T08:30:00Z"
  }
}
```

#### Intake Record Event
```json
{
  "type": "intake_recorded",
  "data": {
    "metric_id": "metric-uuid",
    "record_id": "record-uuid",
    "value": 500,
    "recorded_at": "2024-01-15T08:30:00Z"
  }
}
```

#### Goal Achievement Event
```json
{
  "type": "goal_achieved",
  "data": {
    "habit_id": "habit-uuid",
    "metric_id": "metric-uuid",
    "goal_target": 2000,
    "current_value": 2000,
    "auto_completed": true
  }
}
```

## Push Notifications

### Register Device Token
```http
POST /api/notifications/devices
```

**Request Body:**
```json
{
  "token": "device_token_here",
  "platform": "ios",
  "app_version": "1.0.0"
}
```

### Update Notification Settings
```http
PUT /api/notifications/settings
```

**Request Body:**
```json
{
  "habit_reminders": true,
  "goal_achievements": true,
  "daily_summary": true,
  "weekly_report": true
}
```

---

# Client-Specific Optimizations

## TUI Client

### Compact Endpoints
Use the `compact=true` query parameter for minimal data transfer:

```http
GET /api/habits/status?compact=true
```

**Response:**
```json
{
  "data": [
    {
      "id": "habit-uuid",
      "name": "Take vitamins",
      "status": "completed"
    }
  ]
}
```

### Terminal-Friendly Format
Use the `format=terminal` query parameter for structured output:

```http
GET /api/habits/dashboard?format=terminal
```

## Mobile Client

### Offline Sync
```http
GET /api/sync/changes?since=<timestamp>
```

**Response:**
```json
{
  "data": {
    "habits": {
      "created": [],
      "updated": [],
      "deleted": []
    },
    "completions": {
      "created": [],
      "updated": [],
      "deleted": []
    },
    "intake_records": {
      "created": [],
      "updated": [],
      "deleted": []
    }
  },
  "sync_timestamp": "2024-01-15T12:00:00Z"
}
```

### Quick Actions
```http
POST /api/quick/habit-complete/{habit_id}
```

```http
POST /api/quick/intake-record/{metric_id}
```

## Web Client

### Bulk Operations
```http
POST /api/bulk/operations
```

**Request Body:**
```json
{
  "operations": [
    {
      "type": "habit_complete",
      "habit_id": "habit-uuid"
    },
    {
      "type": "intake_record",
      "metric_id": "metric-uuid",
      "value": 500
    }
  ]
}
```

### Export Data
```http
GET /api/export/habits?format=csv&start_date=2024-01-01&end_date=2024-01-31
```

```http
GET /api/export/intake?format=json&metric_ids=metric-uuid-1,metric-uuid-2
```

---

# SDK and Integration

## Webhook Support

### Register Webhook
```http
POST /api/webhooks
```

**Request Body:**
```json
{
  "url": "https://your-app.com/webhook",
  "events": ["habit_completed", "goal_achieved"],
  "secret": "webhook_secret"
}
```

### Webhook Payload
```json
{
  "event": "habit_completed",
  "data": {
    "habit_id": "habit-uuid",
    "completion_id": "completion-uuid",
    "completed_at": "2024-01-15T08:30:00Z"
  },
  "timestamp": "2024-01-15T08:30:00Z",
  "signature": "sha256=..."
}
```

## API Versioning

The API uses URL-based versioning:
- Current version: `/v1/`
- Future versions: `/v2/`, `/v3/`, etc.

Version deprecation notices will be provided via the `X-API-Version-Deprecated` header.

---

This API documentation provides comprehensive coverage of all endpoints for the personal productivity system, optimized for TUI, mobile, and web clients.