Admin User API Documentation

Overview

This document describes the API endpoints available for administrator users. Admin users have elevated privileges to manage reports, moderate content, and manage users.

Authentication

All admin endpoints require authentication via Token Auth:

Authorization: Token <your-token-here>

Admin users must have is_staff=True and an associated Administrator record.

---

Report Management

List All Reports

Get all task and user reports with filtering options.

Endpoint: GET /api/admin/reports/

Query Parameters:

• type - Filter by report type: task, user, or all (default: all)
• status - Filter by status: PENDING, UNDER_REVIEW, RESOLVED, DISMISSED
• page - Page number (default: 1)
• limit - Items per page (default: 20)

Response:

{
  "status": "success",
  "data": {
    "task_reports": {
      "reports": [...],
      "pagination": {...}
    },
    "user_reports": {
      "reports": [...],
      "pagination": {...}
    },
    "statistics": {
      "total_task_reports": 10,
      "pending_task_reports": 3,
      "total_user_reports": 5,
      "pending_user_reports": 2
    }
  }
}

---

Update Report Status

Update the status of a task or user report.

Endpoint: PATCH /api/task-reports/{id}/update-status/ or PATCH /api/user-reports/{id}/update-status/

Request Body:

{
  "status": "UNDER_REVIEW",
  "admin_notes": "Investigating the claim"
}

Status Options: PENDING, UNDER_REVIEW, RESOLVED, DISMISSED

Response:

{
  "status": "success",
  "message": "Report status updated successfully.",
  "data": {
    "id": 1,
    "status": "UNDER_REVIEW",
    "reviewed_by_username": "admin_user",
    "admin_notes": "Investigating the claim",
    "updated_at": "2025-04-24T12:00:00Z"
  }
}

---

User Management

List Reported Users

Get all users who have received reports, sorted by report count.

Endpoint: GET /api/admin/reported-users/

Query Parameters:

• page - Page number (default: 1)
• limit - Items per page (default: 20)

Response:

{
  "status": "success",
  "data": {
    "users": [
      {
        "user_id": 5,
        "username": "problematic_user",
        "email": "[email protected]",
        "is_active": true,
        "report_count": 3,
        "last_reported_at": "2025-04-24T10:30:00Z"
      }
    ],
    "pagination": {...}
  }
}

---

Get User Details

Get detailed information about a specific user including their reports and flagged tasks.

Endpoint: GET /api/admin/users/{user_id}/

Response:

{
  "status": "success",
  "data": {
    "user_id": 5,
    "username": "user123",
    "email": "[email protected]",
    "name": "John",
    "surname": "Doe",
    "phone_number": "1234567890",
    "location": "New York",
    "rating": 4.5,
    "completed_task_count": 10,
    "status": "active",
    "user_reports": [...],
    "user_reports_count": 2,
    "task_reports_count": 1,
    "flagged_tasks": [
      {
        "task_id": 10,
        "task_title": "Suspicious Task",
        "created_at": "2025-04-20T15:00:00Z",
        "report_type": "SPAM",
        "report_description": "This looks like spam"
      }
    ]
  }
}

---

Ban User

Ban a user from the platform (sets is_active to false).

Endpoint: POST /api/admin/users/{user_id}/ban/

Request Body:

{
  "reason": "Multiple violations of community guidelines"
}

Response:

{
  "status": "success",
  "message": "User banned successfully.",
  "data": {
    "user_id": 5,
    "username": "user123",
    "new_status": "banned",
    "banned_at": "2025-04-24T14:30:00Z",
    "reason": "Multiple violations of community guidelines"
  }
}

Note: A system notification is automatically sent to the banned user.

---

Task Management

Delete Task

Permanently delete a task (admin action).

Endpoint: DELETE /api/admin/tasks/{task_id}/delete/

Request Body:

{
  "reason": "Violates community guidelines"
}

Response:

{
  "status": "success",
  "message": "Task deleted successfully.",
  "data": {
    "task_id": 10,
    "title": "Deleted Task",
    "creator_id": 5,
    "creator_username": "user123",
    "reason": "Violates community guidelines"
  }
}

Note: A notification is sent to the task creator informing them of the deletion.

---

Report Types

Task Report Types

• SPAM - Spam content
• INAPPROPRIATE_CONTENT - Inappropriate or offensive content
• HARASSMENT - Harassment or bullying
• FRAUD - Fraudulent activity
• FAKE_REQUEST - Fake or misleading request
• NO_SHOW - User did not show up
• SAFETY_CONCERN - Safety or security concern
• OTHER - Other issues

User Report Types

Same as task report types.

Report Statuses

• PENDING - Newly submitted, awaiting review
• UNDER_REVIEW - Currently being investigated
• RESOLVED - Issue resolved, action taken
• DISMISSED - Report found to be invalid

---

Error Responses

All endpoints return consistent error responses:

{
  "status": "error",
  "message": "Error description",
  "data": {
    "field_name": ["Validation error details"]
  }
}

Common Error Codes:

• 400 - Bad request (validation error)
• 401 - Unauthorized (not authenticated)
• 403 - Forbidden (not an admin)
• 404 - Not found
• 500 - Server error

---

Notes

1. Admin Permissions: All endpoints require the user to have admin privileges (is_staff=True and Administrator record).

2. Audit Trail: All admin actions (ban user, update report status, delete task) are tracked with the admin's user ID and timestamp.

3. Notifications: System automatically sends notifications to affected users when admins take actions (ban, delete task).

4. Cascading Deletes: Deleting a task will also delete all associated reports, comments, reviews, and photos.

5. Report Uniqueness: Each user can only report a specific task or user once. Duplicate reports update the existing report.