[Goto Home](/docs/index.html)

# 🔐 GET `/admin/alerts`

## Description

- Returns a paginated list of all alerts, sorted by `createdAt` descending.

## Request Query

- `limit` – optional, natural number, default `"20"`, number of items per page
- `page` – optional, natural number, default `"1"`, page number

## Response Body

```json
{
  "alerts": [
    {
      "_id": "68a2f0f8a64cd0088270de83",
      "title": "New Feature Available!",
      "description": "Check out the new explore tab with enhanced discovery.",
      "buttonLabel": "Explore Now",
      "photo": "https://...",
      "video": "https://...",
      "action": "explore",
      "event": null,
      "reel": null,
      "link": null,
      "createdAt": "2025-10-09T06:17:19.192Z",
      "updatedAt": "2025-10-09T06:17:19.192Z"
    }
  ],
  "count": 1
}
```

---

# 🔐 GET `/admin/alerts/:id`

## Description

- Returns the details of a single alert by its `_id`.

## Request Params

- `id` – required, MongoDB ObjectId of the alert.

## Response Body

```json
{
  "alert": {
    "_id": "68a2f0f8a64cd0088270de83",
    "title": "New Feature Available!",
    "description": "Check out the new explore tab with enhanced discovery.",
    "buttonLabel": "Explore Now",
    "photo": "https://...",
    "video": "https://...",
    "action": "explore",
    "event": null,
    "reel": null,
    "link": null,
    "createdAt": "2025-10-09T06:17:19.192Z",
    "updatedAt": "2025-10-09T06:17:19.192Z"
  }
}
```

## Error Responses

- **404** – Alert not found.

---

# 🔐 POST `/admin/alerts`

## Description

- Creates a new alert.
- If `event` or `reel` is provided, it must exist in the database — returns **404** otherwise.
- Photo and video are uploaded separately via `PUT /admin/alerts/:id/photo` and `PUT /admin/alerts/:id/video`.
- After creation, emits socket event `alert-created` based on `socketNotify`:
  - If `socketNotify` is `false` — no socket notification (use this when a photo/video upload will follow, and notify from that upload instead).
  - If `socketNotify` is `true` (default) — notifies users via socket:
    - If the linked event has a **location** → notifies only **nearby online users** within 25 km of the event.
    - Otherwise → broadcasts to **all users**.

## Request Body (JSON)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| title | string | ✅ | 1–200 characters |
| description | string | ✅ | 1–2000 characters |
| buttonLabel | string | ✅ | 1–100 characters |
| action | string | ✅ | One of: `meetme`, `home`, `reel`, `study`, `event`, `explore`, `chats` |
| event | string | ❌ | MongoDB ObjectId of an existing event |
| reel | string | ❌ | MongoDB ObjectId of an existing reel |
| link | string | ❌ | Valid URL |
| socketNotify | boolean | ❌ | Whether to emit `alert-created` socket event after creation. Default: `true`. Set to `false` when a photo/video upload will follow. |

```json
{
  "title": "New Feature Available!",
  "description": "Check out the new explore tab with enhanced discovery.",
  "buttonLabel": "Explore Now",
  "action": "explore",
  "link": "https://example.com/feature",
  "socketNotify": true
}
```

## Response Body

```json
{
  "alert": {
    "_id": "68a2f0f8a64cd0088270de83",
    "title": "New Feature Available!",
    "description": "Check out the new explore tab with enhanced discovery.",
    "buttonLabel": "Explore Now",
    "action": "explore",
    "link": "https://example.com/feature",
    "createdAt": "2025-10-09T06:17:19.192Z",
    "updatedAt": "2025-10-09T06:17:19.192Z"
  }
}
```

## Error Responses

- **400** – Validation error (missing or invalid fields).
- **404** – Event or reel not found.

---

# 🔐 PUT `/admin/alerts/:id/photo`

## Description

- Uploads or replaces the photo for an alert.
- If a previous photo exists, it is deleted from storage before the new one is saved.
- If `socketNotify=true` is passed as a query param, emits socket event `alert-created` after upload:
  - If the alert has a linked event with a **location** → notifies only **nearby online users** within 25 km.
  - Otherwise → broadcasts to **all users**.

## Request Params

- `id` – required, MongoDB ObjectId of the alert.

## Request Query

- `socketNotify` – optional, boolean string (`true` or `false`). Default: not set (no notification). Pass `true` when this is the final upload step and notification should be sent now.

## Request Body (Form Data)

| Field | Type | Required |
|-------|------|----------|
| photo | file (image) | ✅ |

## Response Body

```json
{
  "photo": "https://...",
  "message": "photo updated successfully"
}
```

## Error Responses

- **400** – No photo file provided.
- **404** – Alert not found.
- **500** – Upload failure.

---

# 🔐 PUT `/admin/alerts/:id/video`

## Description

- Uploads or replaces the video for an alert.
- If a previous video exists, it is deleted from storage before the new one is saved.
- If `socketNotify=true` is passed as a query param, emits socket event `alert-created` after upload:
  - If the alert has a linked event with a **location** → notifies only **nearby online users** within 25 km.
  - Otherwise → broadcasts to **all users**.

## Request Params

- `id` – required, MongoDB ObjectId of the alert.

## Request Query

- `socketNotify` – optional, boolean string (`true` or `false`). Default: not set (no notification). Pass `true` when this is the final upload step and notification should be sent now.

## Request Body (Form Data)

| Field | Type | Required |
|-------|------|----------|
| video | file (video) | ✅ |

## Response Body

```json
{
  "video": "https://...",
  "message": "video updated successfully"
}
```

## Error Responses

- **400** – No video file provided.
- **404** – Alert not found.
- **500** – Upload failure.

---

# 🔐 DELETE `/admin/alerts/:id`

## Description

- Deletes an alert by its `_id`.
- Also deletes the associated photo and video from storage if they exist.
- Also deletes all related `alert-views` documents.

## Request Params

- `id` – required, MongoDB ObjectId of the alert.

## Response Body

```json
{
  "message": "alert deleted successfully"
}
```

## Error Responses

- **404** – Alert not found.

# Links

[Goto Home](/docs/index.html)