Complete API Reference - Commentum v2 Backend Service

🎯 IMPORTANT: This is a backend API service documentation. These endpoints are designed for apps to integrate with, not for end users to access directly.

Base URL: https://whzwmfxngelicmjyxwmr.supabase.co/functions/v1/

🔑 TOKEN-BASED AUTH - Mod+ actions require client_type + access_token for verification with provider APIs.

🚀 Overview

What is Commentum v2?

Commentum v2 is a comment backend API service that provides:

Comment CRUD operations
Voting system
Content reporting
Advanced moderation
Multi-platform support (AniList, MyAnimeList, SIMKL)

Apps integrate with this backend via REST API calls.

🔐 Authentication

Token-Based Authentication (Mod+ Actions)

All moderation and admin actions require token-based authentication:

{
  "client_type": "anilist",
  "access_token": "user_oauth_token_from_provider"
}

The backend verifies the token with the appropriate provider API:

Provider	API Endpoint	Returns
AniList	`graphql.anilist.co`	`id`, `name`, `avatar`
MAL	`api.myanimelist.net/v2/users/@me`	`id`, `name`, `picture`
SIMKL	`api.simkl.com/users/settings`	`account.id`, `user.name`

Frontend-Provided User Information

Basic operations use user_info objects:

{
  "user_info": {
    "user_id": "12345",
    "username": "TestUser",
    "avatar": "https://example.com/avatar.jpg"
  }
}

When Token Auth is Required

Endpoint	Operation	Auth Required
`/comments`	Create	❌ No
`/comments`	Edit	❌ No (user_id match only)
`/comments`	Delete (own)	❌ No (user_id match only)
`/comments`	mod_delete (others)	✅ Token required
`/votes`	Vote	❌ No
`/media`	Get comments	❌ No
`/reports`	Create report	❌ No
`/reports`	Resolve report	✅ Token required
`/reports`	Get queue	✅ Token required
`/moderation`	All actions	✅ Token required
`/users`	All actions	✅ Token required

💬 Comments API

Endpoint: `/comments`

Method: POST

Content-Type: application/json

1. Create Comment

Auth: Not required

{
  "action": "create",
  "client_type": "anilist",
  "user_info": {
    "user_id": "12345",
    "username": "TestUser",
    "avatar": "https://example.com/avatar.jpg"
  },
  "media_info": {
    "media_id": "6789",
    "type": "anime",
    "title": "Attack on Titan",
    "year": 2013,
    "poster": "https://example.com/poster.jpg"
  },
  "content": "This was an amazing episode!",
  "parent_id": null,
  "tag": "1"
}

Response (201):

{
  "success": true,
  "comment": { /* comment object */ }
}

2. Edit Comment

Auth: user_info (owner only)

{
  "action": "edit",
  "comment_id": 1,
  "user_info": {
    "user_id": "12345",
    "username": "TestUser"
  },
  "content": "Updated comment text"
}

3. Delete Comment (Own)

Auth: user_info (owner only)

{
  "action": "delete",
  "comment_id": 1,
  "user_info": {
    "user_id": "12345",
    "username": "TestUser"
  }
}

4. Mod Delete Comment (Other's)

Auth: ✅ Token required (moderator+)

{
  "action": "mod_delete",
  "comment_id": 1,
  "client_type": "anilist",
  "access_token": "user_oauth_token_here"
}

Response (200):

{
  "success": true,
  "comment": { /* deleted comment */ },
  "moderator": {
    "id": "67890",
    "username": "ModeratorUser",
    "role": "admin"
  }
}

🗳️ Votes API

Endpoint: `/votes`

Method: POST

Auth: Not required

{
  "comment_id": 1,
  "user_info": {
    "user_id": "12345",
    "username": "TestUser"
  },
  "vote_type": "upvote"
}

vote_type: "upvote", "downvote", or "remove"

Response (200):

{
  "success": true,
  "voteScore": 5,
  "upvotes": 6,
  "downvotes": 1,
  "userVote": "upvote"
}

🚨 Reports API

Endpoint: `/reports`

Method: POST

1. Create Report

Auth: Not required

{
  "action": "create",
  "comment_id": 1,
  "reporter_info": {
    "user_id": "12345",
    "username": "TestUser"
  },
  "reason": "spam",
  "notes": "This looks like automated spam"
}

Valid Reasons: spam, offensive, harassment, spoiler, nsfw, off_topic, other

2. Resolve Report

Auth: ✅ Token required (moderator+)

{
  "action": "resolve",
  "comment_id": 1,
  "client_type": "anilist",
  "access_token": "user_oauth_token_here",
  "reporter_info": { "user_id": "12345" },
  "resolution": "resolved",
  "review_notes": "Confirmed spam, removed"
}

resolution: "resolved" or "dismissed"

3. Get Reports Queue

Auth: ✅ Token required (moderator+)

{
  "action": "get_queue",
  "client_type": "anilist",
  "access_token": "user_oauth_token_here"
}

🔧 Moderation API

Endpoint: `/moderation`

Method: POST

Auth: ✅ Token required for all actions

Common Parameters

All moderation actions require:

Parameter	Type	Required	Description
`action`	string	✅	Moderation action type
`client_type`	string	✅	`"anilist"`, `"mal"`, `"simkl"`
`access_token`	string	✅	OAuth token from provider

Actions

Pin Comment

{
  "action": "pin_comment",
  "comment_id": 1,
  "client_type": "anilist",
  "access_token": "...",
  "reason": "Important announcement"
}

Unpin Comment

{
  "action": "unpin_comment",
  "comment_id": 1,
  "client_type": "anilist",
  "access_token": "...",
  "reason": "No longer relevant"
}

Lock Thread

{
  "action": "lock_thread",
  "comment_id": 1,
  "client_type": "anilist",
  "access_token": "...",
  "reason": "Off-topic discussion"
}

Unlock Thread

{
  "action": "unlock_thread",
  "comment_id": 1,
  "client_type": "anilist",
  "access_token": "...",
  "reason": "Discussion can continue"
}

Warn User

{
  "action": "warn_user",
  "target_user_id": "12345",
  "client_type": "anilist",
  "access_token": "...",
  "reason": "Multiple rule violations"
}

Ban User (Admin+)

{
  "action": "ban_user",
  "target_user_id": "12345",
  "client_type": "anilist",
  "access_token": "...",
  "reason": "Repeated spam",
  "shadow_ban": false
}

Unban User (Admin+)

{
  "action": "unban_user",
  "target_user_id": "12345",
  "client_type": "anilist",
  "access_token": "...",
  "reason": "Appeal approved"
}

Get Moderation Queue

{
  "action": "get_queue",
  "client_type": "anilist",
  "access_token": "..."
}

👤 Users API

Endpoint: `/users`

Method: POST

Auth: ✅ Token required for all actions

Actions

Get User Info

{
  "action": "get_user_info",
  "client_type": "anilist",
  "access_token": "...",
  "target_user_id": "12345",
  "target_client_type": "anilist"
}

Get User Stats

{
  "action": "get_user_stats",
  "client_type": "anilist",
  "access_token": "...",
  "target_client_type": "anilist"
}

Warn User

{
  "action": "warn_user",
  "client_type": "anilist",
  "access_token": "...",
  "target_user_id": "12345",
  "target_client_type": "anilist",
  "reason": "Rule violation"
}

Mute User

{
  "action": "mute_user",
  "client_type": "anilist",
  "access_token": "...",
  "target_user_id": "12345",
  "target_client_type": "anilist",
  "reason": "Temporary mute",
  "duration": 24
}

Unmute User

{
  "action": "unmute_user",
  "client_type": "anilist",
  "access_token": "...",
  "target_user_id": "12345",
  "target_client_type": "anilist",
  "reason": "Mute expired"
}

Ban User (Admin+)

{
  "action": "ban_user",
  "client_type": "anilist",
  "access_token": "...",
  "target_user_id": "12345",
  "target_client_type": "anilist",
  "reason": "Repeated violations"
}

Unban User (Admin+)

{
  "action": "unban_user",
  "client_type": "anilist",
  "access_token": "...",
  "target_user_id": "12345",
  "target_client_type": "anilist",
  "reason": "Appeal approved"
}

Get User History

{
  "action": "get_user_history",
  "client_type": "anilist",
  "access_token": "...",
  "target_user_id": "12345",
  "target_client_type": "anilist"
}

📺 Media API

Endpoint: `/media`

Method: GET

Auth: Not required

Query Parameters

Parameter	Type	Required	Default	Description
`media_id`	string	✅	-	Media identifier
`client_type`	string	✅	-	Platform identifier
`page`	integer	❌	1	Page number
`limit`	integer	❌	50	Results per page
`sort`	string	❌	newest	Sort order

Sort Options: newest, oldest, top, controversial

Example:

GET /media?media_id=6789&client_type=anilist&page=1&limit=20&sort=top

Response (200):

{
  "media": {
    "mediaId": "6789",
    "mediaType": "anime",
    "mediaTitle": "Attack on Titan",
    "mediaYear": 2023,
    "mediaPoster": "https://example.com/poster.jpg"
  },
  "comments": [ /* nested comment structure */ ],
  "stats": {
    "commentCount": 150,
    "totalUpvotes": 500,
    "totalDownvotes": 50,
    "netScore": 450
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

📢 Announcements API

Endpoint: `/announcements`

Multi-app announcement system for developer communications.

1. List Announcements

Method: GET

Auth: Not required (public)

Query Parameters:

Parameter	Type	Required	Default	Description
`app_id`	string	✅	-	App ID (anymex/shonenx/animestream)
`status`	string	❌	published	Filter by status
`category`	string	❌	-	Filter by category
`page`	integer	❌	1	Page number
`limit`	integer	❌	20	Results per page (max 50)
`user_id`	string	❌	-	For read status
`include_read`	boolean	❌	false	Include read status

Example:

GET /announcements?app_id=anymex&status=published&page=1&limit=20

Response (200):

{
  "success": true,
  "announcements": [
    {
      "id": 1,
      "title": "New Feature Release",
      "short_description": "We've added a new feature...",
      "category": "feature",
      "pinned": true,
      "featured": false,
      "priority": 10,
      "published_at": "2024-01-15T10:00:00Z",
      "author_name": "Dev Team",
      "view_count": 150,
      "is_read": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "total_pages": 3
  },
  "unread_count": 5
}

2. Get Single Announcement

Method: GET

Auth: Not required (public)

Example:

GET /announcements/1?user_id=12345&app_id=anymex

Response (200):

{
  "success": true,
  "announcement": {
    "id": 1,
    "app_id": "anymex",
    "title": "New Feature Release",
    "short_description": "We've added a new feature...",
    "full_content": "# Full markdown content here...",
    "author_id": "dev123",
    "author_name": "Dev Team",
    "category": "feature",
    "priority": 10,
    "status": "published",
    "pinned": true,
    "featured": false,
    "published_at": "2024-01-15T10:00:00Z",
    "expires_at": null,
    "view_count": 151,
    "is_read": false
  }
}

3. Get Unread Count

Method: GET

Auth: Not required

Example:

GET /announcements/unread-count?user_id=12345&app_id=anymex

Response (200):

{
  "success": true,
  "total_published": 45,
  "read_count": 40,
  "unread_count": 5
}