Koko210/miku-discord
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
65e6c3e7eafe2cd6d02cb41ba03d139e6f8907e9
miku-discord/API_REFERENCE.md
koko210Serve a7f3a0a0ee Add comprehensive CLI tool with interactive shell mode 
- Created miku-cli.py: Full-featured CLI for Miku bot API
- Added interactive shell mode for continuous command execution
- Implemented all API endpoints: status, mood, autonomous, DM, blocking, profile pictures
- Consistent hyphenated command naming across shell and regular modes
- Created API_REFERENCE.md: Complete API endpoint documentation
- Created CLI_README.md: User guide with examples and usage instructions
- Error handling and user-friendly output formatting
2025-12-10 10:02:34 +02:00

8.0 KiB
Raw Blame History

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:

{
  "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:

{
  "prompt": "Last prompt text..."
}

😊 Mood Management

GET /mood

Get current DM mood.

Response:

{
  "mood": "neutral",
  "description": "Mood description text..."
}

POST /mood

Set DM mood.

Request Body:

{
  "mood": "bubbly"
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "channel_id": "123456789",
  "message_id": "987654321",
  "emoji": "😊"
}

Error Responses

All endpoints return errors in the following format:

{
  "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.

Reference in New Issue View Git Blame Copy Permalink