campaign_connector/docs/api/endpoints.md

# API Endpoints Reference

Complete reference for all SMS Campaign Manager API endpoints.

## Authentication

All API endpoints (except `/health` and `/login`) require authentication via:
- **API Key** in `X-API-Key` header, or
- **Bearer Token** in `Authorization` header, or
- **Session Cookie** from web login

## Base URLs

- **Ubuntu Server**: `http://localhost:5000`
- **Tailscale**: `http://YOUR_TAILSCALE_IP:5000`
- **Android Termux API**: `http://YOUR_ANDROID_IP:5001`

## Health & Status

### GET /health
Check application health.

**Authentication**: None required

**Response**:
```json
{
  "status": "ok",
  "version": "2.0"
}
```

## Authentication Endpoints

### POST /api/auth/login
User login (web dashboard).

**Authentication**: None required

**Request**:
```json
{
  "username": "admin",
  "password": "your-password"
}
```

**Response**:
```json
{
  "success": true,
  "message": "Login successful",
  "user": {
    "username": "admin",
    "role": "admin"
  },
  "redirect": "/"
}
```

### POST /api/auth/logout
User logout.

**Authentication**: Session cookie required

**Response**:
```json
{
  "success": true,
  "message": "Logged out successfully"
}
```

### GET /api/auth/status
Check authentication status.

**Authentication**: Session cookie required

**Response**:
```json
{
  "authenticated": true,
  "user": {
    "username": "admin",
    "role": "admin"
  }
}
```

## Campaign Management

### GET /api/campaign/list
List all campaigns.

**Authentication**: User API key required

**Response**:
```json
[
  {
    "id": 1,
    "name": "Spring Sale",
    "status": "active",
    "created_at": "2025-12-30 10:00:00",
    "total_contacts": 100,
    "sent": 50,
    "failed": 2
  }
]
```

### POST /api/campaign/create
Create new campaign.

**Authentication**: User API key required

**Request**:
```json
{
  "name": "Campaign Name",
  "message_template": "Hi {name}, special offer for you!",
  "contact_list_id": 1
}
```

**Response**:
```json
{
  "success": true,
  "campaign_id": 5,
  "message": "Campaign created successfully"
}
```

### POST /api/campaign/start
Start a campaign.

**Authentication**: User API key required

**Request**:
```json
{
  "campaign_id": 5
}
```

**Response**:
```json
{
  "success": true,
  "message": "Campaign started"
}
```

### POST /api/campaign/pause
Pause running campaign.

**Authentication**: User API key required

**Request**:
```json
{
  "campaign_id": 5
}
```

**Response**:
```json
{
  "success": true,
  "message": "Campaign paused"
}
```

### POST /api/campaign/resume
Resume paused campaign.

**Authentication**: User API key required

**Request**:
```json
{
  "campaign_id": 5
}
```

**Response**:
```json
{
  "success": true,
  "message": "Campaign resumed"
}
```

### GET /api/campaign/status
Get campaign status and progress.

**Authentication**: User API key required

**Query Parameters**:
- `campaign_id` (required): Campaign ID

**Response**:
```json
{
  "id": 5,
  "name": "Spring Sale",
  "status": "running",
  "progress": {
    "total": 100,
    "sent": 45,
    "failed": 2,
    "pending": 53,
    "percentage": 45
  }
}
```

## SMS Operations

### POST /api/sms/send/enhanced
Send SMS via Termux API with retry logic.

**Authentication**: User API key required

**Request**:
```json
{
  "phone": "+1234567890",
  "message": "Hello from SMS Campaign Manager!"
}
```

**Response**:
```json
{
  "success": true,
  "method": "termux_api",
  "message": "SMS sent successfully",
  "timestamp": "2025-12-30 14:30:00"
}
```

### POST /api/sms/test
Send test SMS (simulation, no actual SMS sent).

**Authentication**: User API key required

**Request**:
```json
{
  "phone": "+1234567890",
  "message": "Test message"
}
```

**Response**:
```json
{
  "success": true,
  "message": "Test SMS simulated successfully",
  "details": {
    "phone": "+1234567890",
    "message_length": 12,
    "estimated_cost": 0.01
  }
}
```

### GET /api/sms/status
Get SMS sending status and statistics.

**Authentication**: User API key required

**Response**:
```json
{
  "total_sent": 1250,
  "total_failed": 15,
  "success_rate": 98.8,
  "last_24h": {
    "sent": 120,
    "failed": 2
  },
  "connection_method": "termux_api"
}
```

## File Upload

### POST /api/csv/upload
Upload CSV file with contacts.

**Authentication**: User API key required

**Request**: `multipart/form-data`
- `file`: CSV file with columns: `phone`, `name` (optional: `message`, `email`, etc.)

**Response**:
```json
{
  "success": true,
  "filename": "contacts_20251230.csv",
  "contacts_imported": 150,
  "list_id": 3
}
```

### POST /api/campaign/upload
Upload CSV and create campaign in one step.

**Authentication**: User API key required

**Request**: `multipart/form-data`
- `file`: CSV file
- `campaign_name`: Campaign name
- `message_template`: Message template with {variables}

**Response**:
```json
{
  "success": true,
  "campaign_id": 6,
  "contacts_imported": 150,
  "message": "Campaign created and ready to start"
}
```

## Phone/Device Status

### GET /api/phone/status
Check Android device connection and status.

**Authentication**: User API key required

**Response**:
```json
{
  "connected": true,
  "ip_address": "100.107.173.66",
  "termux_api": {
    "available": true,
    "port": 5001,
    "last_check": "2025-12-30 14:35:00"
  },
  "adb": {
    "available": false,
    "fallback_mode": false
  },
  "battery": {
    "percentage": 85,
    "status": "charging"
  }
}
```

## Database Operations

### GET /api/database/stats
Get database statistics.

**Authentication**: User API key required

**Response**:
```json
{
  "campaigns": 12,
  "contacts": 5430,
  "messages_sent": 15280,
  "success_rate": 98.2,
  "database_size_mb": 45.6,
  "users": 5
}
```

### POST /api/database/reset
Reset database (destructive operation).

**Authentication**: **Admin API key required**

**Request**:
```json
{
  "confirm": true
}
```

**Response**:
```json
{
  "success": true,
  "message": "Database reset successfully",
  "warning": "All data has been deleted"
}
```

## Admin Endpoints

### GET /api/admin/users
List all users (admin only).

**Authentication**: Session cookie + admin role required

**Response**:
```json
[
  {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "created_at": "2025-12-30 10:00:00",
    "last_login": "2025-12-30 14:00:00",
    "is_active": true
  },
  {
    "id": 2,
    "username": "user1",
    "role": "user",
    "created_at": "2025-12-30 11:00:00",
    "is_active": true
  }
]
```

### POST /api/admin/users/create
Create new user (admin only).

**Authentication**: Session cookie + admin role required

**Request**:
```json
{
  "username": "newuser",
  "password": "SecurePassword123!",
  "role": "user",
  "email": "user@example.com",
  "full_name": "New User"
}
```

**Response**:
```json
{
  "success": true,
  "user_id": 3,
  "message": "User created successfully"
}
```

### DELETE /api/admin/users/<username>
Delete user (admin only).

**Authentication**: Session cookie + admin role required

**Response**:
```json
{
  "success": true,
  "message": "User deleted successfully"
}
```

## Android Termux API Endpoints

Base URL: `http://YOUR_ANDROID_IP:5001`

### GET /health
Check Termux API server health.

**Authentication**: None required

**Response**:
```json
{
  "status": "healthy",
  "uptime_seconds": 3600,
  "version": "1.0"
}
```

### POST /api/sms/send
Send SMS via Termux API (internal use).

**Authentication**: Termux API key required

**Request**:
```json
{
  "phone": "+1234567890",
  "message": "Hello!"
}
```

**Response**:
```json
{
  "success": true,
  "message": "SMS sent successfully",
  "timestamp": "2025-12-30 14:40:00"
}
```

### GET /api/device/battery
Get Android device battery status.

**Authentication**: Termux API key required

**Response**:
```json
{
  "percentage": 85,
  "status": "charging",
  "temperature": 32.5,
  "health": "good"
}
```

## Error Responses

All endpoints may return these error statuses:

### 401 Unauthorized
```json
{
  "error": "Authentication required",
  "message": "Please provide valid API key or login"
}
```

### 403 Forbidden
```json
{
  "error": "Insufficient permissions",
  "message": "Admin role required for this operation"
}
```

### 404 Not Found
```json
{
  "error": "Resource not found",
  "message": "Campaign with ID 999 does not exist"
}
```

### 429 Too Many Requests
```json
{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please wait before trying again."
}
```

### 500 Internal Server Error
```json
{
  "error": "Internal server error",
  "message": "An unexpected error occurred",
  "details": "Error details here"
}
```

## Rate Limits

Default rate limits per IP address:

- `/api/auth/login`: 5 requests/minute
- `/api/sms/*`: 10 requests/minute, 100/hour, 500/day
- `/api/csv/upload`: 10 requests/hour, 50/day
- `/api/database/reset`: 2 requests/hour
- All other endpoints: 200 requests/hour, 1000/day

Rate limit headers included in responses:
```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1767117854
```

## Usage Examples

### Using curl

```bash
# With API key header
curl -H "X-API-Key: YOUR_API_KEY" \
  http://localhost:5000/api/campaign/list

# With Bearer token
curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:5000/api/campaign/list

# POST with JSON data
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+1234567890","message":"Hello"}' \
  http://localhost:5000/api/sms/send/enhanced

# File upload
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@contacts.csv" \
  http://localhost:5000/api/csv/upload
```

### Using Python requests

```python
import requests

API_KEY = "your-api-key-here"
BASE_URL = "http://localhost:5000"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# List campaigns
response = requests.get(f"{BASE_URL}/api/campaign/list", headers=headers)
campaigns = response.json()

# Send SMS
data = {
    "phone": "+1234567890",
    "message": "Hello from Python!"
}
response = requests.post(
    f"{BASE_URL}/api/sms/send/enhanced",
    headers=headers,
    json=data
)
print(response.json())

# Upload CSV
files = {"file": open("contacts.csv", "rb")}
response = requests.post(
    f"{BASE_URL}/api/csv/upload",
    headers={"X-API-Key": API_KEY},
    files=files
)
print(response.json())
```

## Related Documentation

- [API Security](../security/api-security.md)
- [Authentication Setup](../setup/authentication.md)
- [Quick Start Guide](../setup/quick-start.md)