# Moderation Service API

> REST API documentation for the Aphrodite Moderation Service.

**Base URL:** `https://api.aphrodite.example.com/api/v1/moderation` **Port:**
7002 **Authentication:** JWT Bearer Token

---

## Table of Contents

1. [Content Moderation](#content-moderation)
2. [User Reports](#user-reports)
3. [Chat Moderation](#chat-moderation)
4. [Appeals](#appeals)
5. [Moderator Actions](#moderator-actions)

---

## Content Moderation

### Submit Content for Moderation

Manually submit content for moderation review.

```http
POST /content/submit
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "contentId": "cnt_abc123",
  "contentType": "image",
  "priority": "normal"
}
```

**Response (202 Accepted):**

```json
{
  "success": true,
  "data": {
    "moderationId": "mod_xyz789",
    "contentId": "cnt_abc123",
    "status": "pending",
    "estimatedReviewTime": 300,
    "submittedAt": "2026-01-18T12:00:00.000Z"
  }
}
```

---

### Get Moderation Status

```http
GET /content/:contentId/status
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "contentId": "cnt_abc123",
    "moderationId": "mod_xyz789",
    "status": "approved",
    "aiScore": {
      "safe": 0.95,
      "adult": 0.85,
      "explicit": 0.75,
      "violence": 0.02,
      "hate": 0.01
    },
    "flags": [],
    "reviewedBy": "ai",
    "reviewedAt": "2026-01-18T12:01:00.000Z"
  }
}
```

**Moderation Status Values:**

| Status             | Description                     |
| ------------------ | ------------------------------- |
| `pending`          | Awaiting review                 |
| `in_review`        | Currently being reviewed        |
| `approved`         | Content approved for publishing |
| `rejected`         | Content rejected                |
| `requires_changes` | Content needs modifications     |
| `escalated`        | Escalated for human review      |

---

### Get Content Guidelines

```http
GET /guidelines
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "categories": [
      {
        "id": "adult_content",
        "name": "Adult Content",
        "description": "Guidelines for adult content",
        "allowed": true,
        "rules": [
          "All participants must be verified adults (18+)",
          "All content must be consensual",
          "Creator must have proper age verification"
        ]
      },
      {
        "id": "prohibited",
        "name": "Prohibited Content",
        "description": "Content that is never allowed",
        "allowed": false,
        "rules": [
          "No underage individuals or CSAM",
          "No non-consensual content",
          "No violence or gore",
          "No illegal activities"
        ]
      }
    ],
    "version": "2.1.0",
    "lastUpdated": "2026-01-01T00:00:00.000Z"
  }
}
```

---

## User Reports

### Submit Report

Report a user, content, or stream.

```http
POST /reports
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "targetType": "content",
  "targetId": "cnt_abc123",
  "reason": "prohibited_content",
  "description": "This content appears to violate community guidelines",
  "evidence": [
    {
      "type": "screenshot",
      "url": "https://uploads.aphrodite.example.com/evidence/ev_123.jpg"
    },
    {
      "type": "timestamp",
      "value": "2026-01-18T12:30:00.000Z"
    }
  ]
}
```

**Response (201 Created):**

```json
{
  "success": true,
  "data": {
    "reportId": "rpt_abc123",
    "status": "submitted",
    "targetType": "content",
    "targetId": "cnt_abc123",
    "reason": "prohibited_content",
    "submittedAt": "2026-01-18T12:00:00.000Z",
    "estimatedReviewTime": 86400
  }
}
```

**Report Reasons:**

| Reason               | Description                   |
| -------------------- | ----------------------------- |
| `prohibited_content` | Content violates guidelines   |
| `harassment`         | Harassment or bullying        |
| `spam`               | Spam or misleading content    |
| `impersonation`      | Impersonating another person  |
| `underage`           | Suspected underage individual |
| `non_consensual`     | Non-consensual content        |
| `illegal_activity`   | Illegal activities            |
| `copyright`          | Copyright infringement        |
| `other`              | Other violation               |

---

### Get Report Status

```http
GET /reports/:reportId
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "reportId": "rpt_abc123",
    "status": "resolved",
    "targetType": "content",
    "targetId": "cnt_abc123",
    "reason": "prohibited_content",
    "resolution": {
      "action": "content_removed",
      "message": "The reported content has been removed for violating our community guidelines.",
      "resolvedAt": "2026-01-18T14:00:00.000Z"
    },
    "submittedAt": "2026-01-18T12:00:00.000Z"
  }
}
```

---

### Get User's Reports

```http
GET /reports/my?status=all&cursor=<cursor>&limit=20
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": [
    {
      "reportId": "rpt_abc123",
      "status": "resolved",
      "targetType": "content",
      "reason": "prohibited_content",
      "submittedAt": "2026-01-18T12:00:00.000Z",
      "resolvedAt": "2026-01-18T14:00:00.000Z"
    }
  ],
  "pagination": {
    "cursor": "next_cursor",
    "hasMore": false,
    "total": 3
  }
}
```

---

## Chat Moderation

### Get Room Moderation Settings

```http
GET /chat/rooms/:roomId/settings
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "roomId": "room_abc123",
    "settings": {
      "slowMode": {
        "enabled": true,
        "interval": 30
      },
      "subscriberOnly": false,
      "followerOnly": {
        "enabled": true,
        "minFollowTime": 600
      },
      "emoteOnly": false,
      "linksAllowed": false,
      "autoModeration": {
        "enabled": true,
        "filterProfanity": true,
        "filterLinks": true,
        "filterSpam": true,
        "customBlockedWords": ["badword1", "badword2"]
      }
    },
    "moderators": [
      {
        "userId": "usr_mod1",
        "username": "moderator1",
        "permissions": ["timeout", "ban", "delete_messages"]
      }
    ]
  }
}
```

---

### Update Room Moderation Settings

```http
PUT /chat/rooms/:roomId/settings
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "slowMode": {
    "enabled": true,
    "interval": 60
  },
  "followerOnly": {
    "enabled": true,
    "minFollowTime": 300
  }
}
```

**Response (200 OK):** Updated settings object.

---

### Add Room Moderator

```http
POST /chat/rooms/:roomId/moderators
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "userId": "usr_mod2",
  "permissions": ["timeout", "delete_messages"]
}
```

**Response (201 Created):**

```json
{
  "success": true,
  "data": {
    "userId": "usr_mod2",
    "username": "moderator2",
    "permissions": ["timeout", "delete_messages"],
    "addedAt": "2026-01-18T12:00:00.000Z"
  }
}
```

---

### Remove Room Moderator

```http
DELETE /chat/rooms/:roomId/moderators/:userId
Authorization: Bearer <access_token>
```

**Response (204 No Content)**

---

### Timeout User

```http
POST /chat/rooms/:roomId/timeout
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "userId": "usr_trouble1",
  "duration": 600,
  "reason": "Spam"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "userId": "usr_trouble1",
    "roomId": "room_abc123",
    "action": "timeout",
    "duration": 600,
    "expiresAt": "2026-01-18T12:10:00.000Z",
    "reason": "Spam",
    "moderatorId": "usr_mod1"
  }
}
```

---

### Ban User from Room

```http
POST /chat/rooms/:roomId/ban
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "userId": "usr_trouble1",
  "reason": "Repeated harassment",
  "permanent": true
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "userId": "usr_trouble1",
    "roomId": "room_abc123",
    "action": "ban",
    "permanent": true,
    "reason": "Repeated harassment",
    "moderatorId": "usr_mod1",
    "bannedAt": "2026-01-18T12:00:00.000Z"
  }
}
```

---

### Unban User

```http
DELETE /chat/rooms/:roomId/ban/:userId
Authorization: Bearer <access_token>
```

**Response (204 No Content)**

---

### Get Banned Users

```http
GET /chat/rooms/:roomId/bans?cursor=<cursor>&limit=20
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": [
    {
      "userId": "usr_trouble1",
      "username": "troublemaker",
      "reason": "Repeated harassment",
      "permanent": true,
      "bannedBy": "usr_mod1",
      "bannedAt": "2026-01-18T12:00:00.000Z"
    }
  ],
  "pagination": {
    "cursor": "next_cursor",
    "hasMore": false,
    "total": 5
  }
}
```

---

### Delete Message

```http
DELETE /chat/messages/:messageId
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "reason": "Inappropriate content"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "messageId": "msg_abc123",
    "deleted": true,
    "deletedBy": "usr_mod1",
    "reason": "Inappropriate content"
  }
}
```

---

## Appeals

### Submit Appeal

Appeal a moderation decision.

```http
POST /appeals
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "actionId": "act_xyz789",
  "actionType": "content_removal",
  "reason": "I believe this content was mistakenly flagged",
  "evidence": "The content shows a medical procedure which is educational in nature"
}
```

**Response (201 Created):**

```json
{
  "success": true,
  "data": {
    "appealId": "apl_abc123",
    "actionId": "act_xyz789",
    "actionType": "content_removal",
    "status": "submitted",
    "submittedAt": "2026-01-18T12:00:00.000Z",
    "estimatedReviewTime": 172800
  }
}
```

---

### Get Appeal Status

```http
GET /appeals/:appealId
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "appealId": "apl_abc123",
    "actionId": "act_xyz789",
    "actionType": "content_removal",
    "status": "approved",
    "originalAction": {
      "type": "content_removal",
      "contentId": "cnt_abc123",
      "takenAt": "2026-01-17T12:00:00.000Z"
    },
    "resolution": {
      "decision": "overturned",
      "message": "After review, we have determined this content does not violate our guidelines. The content has been restored.",
      "restoredAt": "2026-01-19T10:00:00.000Z"
    },
    "submittedAt": "2026-01-18T12:00:00.000Z",
    "resolvedAt": "2026-01-19T10:00:00.000Z"
  }
}
```

---

### Get User Appeals History

```http
GET /appeals/my?status=all&cursor=<cursor>&limit=20
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": [
    {
      "appealId": "apl_abc123",
      "actionType": "content_removal",
      "status": "approved",
      "submittedAt": "2026-01-18T12:00:00.000Z",
      "resolvedAt": "2026-01-19T10:00:00.000Z"
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}
```

---

## Moderator Actions

### Get Moderation Queue (Creator)

```http
GET /queue?status=pending&cursor=<cursor>&limit=20
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": [
    {
      "id": "qi_abc123",
      "type": "report",
      "targetType": "chat_message",
      "targetId": "msg_xyz789",
      "reason": "harassment",
      "priority": "high",
      "reporter": {
        "id": "usr_reporter1",
        "username": "reporter1"
      },
      "target": {
        "userId": "usr_trouble1",
        "username": "troublemaker",
        "content": "Offensive message content..."
      },
      "submittedAt": "2026-01-18T12:00:00.000Z"
    }
  ],
  "pagination": {
    "cursor": "next_cursor",
    "hasMore": true,
    "total": 15
  },
  "stats": {
    "pending": 15,
    "inReview": 3,
    "resolved": 245
  }
}
```

---

### Take Moderation Action

```http
POST /actions
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "queueItemId": "qi_abc123",
  "action": "timeout",
  "duration": 3600,
  "reason": "Harassment of other users",
  "notifyUser": true
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "actionId": "act_xyz789",
    "queueItemId": "qi_abc123",
    "action": "timeout",
    "targetUserId": "usr_trouble1",
    "duration": 3600,
    "reason": "Harassment of other users",
    "takenBy": "usr_creator1",
    "takenAt": "2026-01-18T12:05:00.000Z"
  }
}
```

**Available Actions:**

| Action           | Description                     | Parameters               |
| ---------------- | ------------------------------- | ------------------------ |
| `dismiss`        | Dismiss report (no action)      | `reason`                 |
| `warn`           | Send warning to user            | `reason`, `notifyUser`   |
| `timeout`        | Temporary chat restriction      | `duration`, `reason`     |
| `ban`            | Ban from room/channel           | `permanent`, `reason`    |
| `delete_content` | Remove content                  | `reason`                 |
| `restrict`       | Restrict account features       | `restrictions`, `reason` |
| `suspend`        | Suspend account                 | `duration`, `reason`     |
| `escalate`       | Escalate to platform moderators | `notes`                  |

---

### Get Moderation History

```http
GET /history?targetId=usr_trouble1&cursor=<cursor>&limit=20
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": [
    {
      "actionId": "act_xyz789",
      "action": "timeout",
      "reason": "Harassment of other users",
      "duration": 3600,
      "takenBy": {
        "id": "usr_mod1",
        "username": "moderator1"
      },
      "takenAt": "2026-01-18T12:05:00.000Z",
      "expiresAt": "2026-01-18T13:05:00.000Z",
      "appealed": false
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 3
  }
}
```

---

## Data Types

### Report Object

```typescript
interface Report {
  reportId: string;
  targetType: 'user' | 'content' | 'message' | 'stream';
  targetId: string;
  reason: string;
  description?: string;
  evidence?: Evidence[];
  status: 'submitted' | 'in_review' | 'resolved' | 'dismissed';
  resolution?: Resolution;
  submittedAt: string;
  resolvedAt?: string;
}
```

### Moderation Action Object

```typescript
interface ModerationAction {
  actionId: string;
  action: string;
  targetUserId: string;
  reason: string;
  duration?: number;
  permanent?: boolean;
  takenBy: string;
  takenAt: string;
  expiresAt?: string;
  appealed: boolean;
}
```

---

## Document History

| Date       | Version | Changes                             |
| ---------- | ------- | ----------------------------------- |
| 2026-01-18 | 1.0.0   | Initial Moderation Service API docs |
