miku-discord/API_REFERENCE.md

# Miku Discord Bot API Reference

The Miku bot exposes a FastAPI REST API on port 3939 for controlling and monitoring the bot.

## Base URL
```
http://localhost:3939
```

## API Endpoints

### 📊 Status & Information

#### `GET /status`
Get current bot status and overview.

**Response:**
```json
{
  "status": "online",
  "mood": "neutral",
  "servers": 2,
  "active_schedulers": 2,
  "server_moods": {
    "123456789": "bubbly",
    "987654321": "excited"
  }
}
```

#### `GET /logs`
Get the last 100 lines of bot logs.

**Response:** Plain text log output

#### `GET /prompt`
Get the last full prompt sent to the LLM.

**Response:**
```json
{
  "prompt": "Last prompt text..."
}
```

---

### 😊 Mood Management

#### `GET /mood`
Get current DM mood.

**Response:**
```json
{
  "mood": "neutral",
  "description": "Mood description text..."
}
```

#### `POST /mood`
Set DM mood.

**Request Body:**
```json
{
  "mood": "bubbly"
}
```

**Response:**
```json
{
  "status": "ok",
  "new_mood": "bubbly"
}
```

#### `POST /mood/reset`
Reset DM mood to neutral.

#### `POST /mood/calm`
Calm Miku down (set to neutral).

#### `GET /servers/{guild_id}/mood`
Get mood for specific server.

#### `POST /servers/{guild_id}/mood`
Set mood for specific server.

**Request Body:**
```json
{
  "mood": "excited"
}
```

#### `POST /servers/{guild_id}/mood/reset`
Reset server mood to neutral.

#### `GET /servers/{guild_id}/mood/state`
Get complete mood state for server.

#### `GET /moods/available`
List all available moods.

**Response:**
```json
{
  "moods": {
    "neutral": "😊",
    "bubbly": "🥰",
    "excited": "🤩",
    "sleepy": "😴",
    ...
  }
}
```

---

### 😴 Sleep Management

#### `POST /sleep`
Force Miku to sleep.

#### `POST /wake`
Wake Miku up.

#### `POST /bedtime?guild_id={guild_id}`
Send bedtime reminder. If `guild_id` is provided, sends only to that server.

---

### 🤖 Autonomous Actions

#### `POST /autonomous/general?guild_id={guild_id}`
Trigger autonomous general message.

#### `POST /autonomous/engage?guild_id={guild_id}`
Trigger autonomous user engagement.

#### `POST /autonomous/tweet?guild_id={guild_id}`
Trigger autonomous tweet sharing.

#### `POST /autonomous/reaction?guild_id={guild_id}`
Trigger autonomous reaction to a message.

#### `POST /autonomous/custom?guild_id={guild_id}`
Send custom autonomous message.

**Request Body:**
```json
{
  "prompt": "Say something funny about cats"
}
```

#### `GET /autonomous/stats`
Get autonomous engine statistics for all servers.

**Response:** Detailed stats including message counts, activity, mood profiles, etc.

#### `GET /autonomous/v2/stats/{guild_id}`
Get autonomous V2 stats for specific server.

#### `GET /autonomous/v2/check/{guild_id}`
Check if autonomous action should happen for server.

#### `GET /autonomous/v2/status`
Get autonomous V2 status across all servers.

---

### 🌐 Server Management

#### `GET /servers`
List all configured servers.

**Response:**
```json
{
  "servers": [
    {
      "guild_id": 123456789,
      "guild_name": "My Server",
      "autonomous_channel_id": 987654321,
      "autonomous_channel_name": "general",
      "bedtime_channel_ids": [111111111],
      "enabled_features": ["autonomous", "bedtime"]
    }
  ]
}
```

#### `POST /servers`
Add a new server configuration.

**Request Body:**
```json
{
  "guild_id": 123456789,
  "guild_name": "My Server",
  "autonomous_channel_id": 987654321,
  "autonomous_channel_name": "general",
  "bedtime_channel_ids": [111111111],
  "enabled_features": ["autonomous", "bedtime"]
}
```

#### `DELETE /servers/{guild_id}`
Remove server configuration.

#### `PUT /servers/{guild_id}`
Update server configuration.

#### `POST /servers/{guild_id}/bedtime-range`
Set bedtime range for server.

#### `POST /servers/{guild_id}/memory`
Update server memory/context.

#### `GET /servers/{guild_id}/memory`
Get server memory/context.

#### `POST /servers/repair`
Repair server configurations.

---

### 💬 DM Management

#### `GET /dms/users`
List all users with DM history.

**Response:**
```json
{
  "users": [
    {
      "user_id": "123456789",
      "username": "User#1234",
      "total_messages": 42,
      "last_message_date": "2025-12-10T12:34:56",
      "is_blocked": false
    }
  ]
}
```

#### `GET /dms/users/{user_id}`
Get details for specific user.

#### `GET /dms/users/{user_id}/conversations`
Get conversation history for user.

#### `GET /dms/users/{user_id}/search?query={query}`
Search user's DM history.

#### `GET /dms/users/{user_id}/export`
Export user's DM history.

#### `DELETE /dms/users/{user_id}`
Delete user's DM data.

#### `POST /dm/{user_id}/custom`
Send custom DM (LLM-generated).

**Request Body:**
```json
{
  "prompt": "Ask about their day"
}
```

#### `POST /dm/{user_id}/manual`
Send manual DM (direct message).

**Form Data:**
- `message`: Message text

#### `GET /dms/blocked-users`
List blocked users.

#### `POST /dms/users/{user_id}/block`
Block a user.

#### `POST /dms/users/{user_id}/unblock`
Unblock a user.

#### `POST /dms/users/{user_id}/conversations/{conversation_id}/delete`
Delete specific conversation.

#### `POST /dms/users/{user_id}/conversations/delete-all`
Delete all conversations for user.

#### `POST /dms/users/{user_id}/delete-completely`
Completely delete user data.

---

### 📊 DM Analysis

#### `POST /dms/analysis/run`
Run analysis on all DM conversations.

#### `POST /dms/users/{user_id}/analyze`
Analyze specific user's DMs.

#### `GET /dms/analysis/reports`
Get all analysis reports.

#### `GET /dms/analysis/reports/{user_id}`
Get analysis report for specific user.

---

### 🖼️ Profile Picture Management

#### `POST /profile-picture/change?guild_id={guild_id}`
Change profile picture. Optionally upload custom image.

**Form Data:**
- `file`: Image file (optional)

**Response:**
```json
{
  "status": "ok",
  "message": "Profile picture changed successfully",
  "source": "danbooru",
  "metadata": {
    "url": "https://...",
    "tags": ["hatsune_miku", "...]
  }
}
```

#### `GET /profile-picture/metadata`
Get current profile picture metadata.

#### `POST /profile-picture/restore-fallback`
Restore original fallback profile picture.

---

### 🎨 Role Color Management

#### `POST /role-color/custom`
Set custom role color.

**Form Data:**
- `hex_color`: Hex color code (e.g., "#FF0000")

#### `POST /role-color/reset-fallback`
Reset role color to fallback (#86cecb).

---

### 💬 Conversation Management

#### `GET /conversation/{user_id}`
Get conversation history for user.

#### `POST /conversation/reset`
Reset conversation history.

**Request Body:**
```json
{
  "user_id": "123456789"
}
```

---

### 📨 Manual Messaging

#### `POST /manual/send`
Send manual message to channel.

**Form Data:**
- `message`: Message text
- `channel_id`: Channel ID
- `files`: Files to attach (optional, multiple)

---

### 🎁 Figurine Notifications

#### `GET /figurines/subscribers`
List figurine subscribers.

#### `POST /figurines/subscribers`
Add figurine subscriber.

#### `DELETE /figurines/subscribers/{user_id}`
Remove figurine subscriber.

#### `POST /figurines/send_now`
Send figurine notification to all subscribers.

#### `POST /figurines/send_to_user`
Send figurine notification to specific user.

---

### 🖼️ Image Generation

#### `POST /image/generate`
Generate image using image generation service.

#### `GET /image/status`
Get image generation service status.

#### `POST /image/test-detection`
Test face detection on uploaded image.

---

### 😀 Message Reactions

#### `POST /messages/react`
Add reaction to a message.

**Request Body:**
```json
{
  "channel_id": "123456789",
  "message_id": "987654321",
  "emoji": "😊"
}
```

---

## Error Responses

All endpoints return errors in the following format:

```json
{
  "status": "error",
  "message": "Error description"
}
```

HTTP status codes:
- `200` - Success
- `400` - Bad request
- `404` - Not found
- `500` - Internal server error

## Authentication

Currently, the API does not require authentication. It's designed to run on localhost within a Docker network.

## Rate Limiting

No rate limiting is currently implemented.