# IHMS Website CMS - API Documentation

## Overview

Base URL: `http://localhost:4000/api` (local) or `https://yourdomain.com/api` (production)

All API responses follow a standard format:

```json
{
  "status": "success" | "error",
  "message": "Human-readable message",
  "data": { ... },
  "errors": { ... }  // Only on validation errors
}
```

Paginated responses include a `meta` object:

```json
{
  "status": "success",
  "data": [ ... ],
  "meta": {
    "total": 50,
    "page": 1,
    "limit": 10,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}
```

---

## Authentication

### Login
```
POST /api/auth/login
Content-Type: application/json

{
  "email": "admin@ihms.com",
  "password": "admin123"
}
```

**Response (200):**
```json
{
  "status": "success",
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "admin": {
      "id": "uuid",
      "name": "Super Admin",
      "email": "admin@ihms.com",
      "role": "super_admin"
    }
  }
}
```

### Get Authenticated Admin
```
GET /api/auth/me
Authorization: Bearer {token}
```

**Response (200):**
```json
{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Super Admin",
    "email": "admin@ihms.com",
    "role": "super_admin",
    "created_at": "2026-01-01 00:00:00"
  }
}
```

---

## Blog Posts

### List All Blog Posts
```
GET /api/blogs?page=1&limit=10&status=active
Authorization: Bearer {token}
```

| Query Param | Type   | Default | Description                    |
|-------------|--------|---------|--------------------------------|
| page        | int    | 1       | Page number                    |
| limit       | int    | 10      | Items per page (max 50)        |
| status      | string | -       | Filter: active, inactive, draft |

### Get Single Blog Post
```
GET /api/blogs/{id}
Authorization: Bearer {token}
```

### Create Blog Post
```
POST /api/blogs
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Understanding Health Insurance",
  "description": "A comprehensive guide...",
  "cover_image_url": "https://example.com/image.jpg",
  "content_blocks": [
    {
      "id": "block-1",
      "type": "heading_text",
      "data": { "text": "Introduction" }
    },
    {
      "id": "block-2",
      "type": "text_box",
      "data": { "text": "Content here..." }
    }
  ],
  "status": "active",
  "seo_title": "SEO Title",
  "seo_description": "SEO Description",
  "seo_keywords": "keyword1, keyword2"
}
```

### Update Blog Post
```
PUT /api/blogs/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Updated Title",
  "status": "draft"
}
```

### Toggle Blog Status
```
PATCH /api/blogs/{id}/toggle-status
Authorization: Bearer {token}
```

### Delete Blog Post
```
DELETE /api/blogs/{id}
Authorization: Bearer {token}
```

---

## News Posts

### List All News Posts
```
GET /api/news?page=1&limit=10&tag_id=uuid&status=active
Authorization: Bearer {token}
```

| Query Param | Type   | Default | Description                    |
|-------------|--------|---------|--------------------------------|
| page        | int    | 1       | Page number                    |
| limit       | int    | 10      | Items per page (max 50)        |
| tag_id      | string | -       | Filter by tag ID               |
| status      | string | -       | Filter: active, inactive       |

### Get Single News Post
```
GET /api/news/{id}
Authorization: Bearer {token}
```

### Create News Post
```
POST /api/news
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "New Partnership Announcement",
  "content": "Full news content...",
  "cover_image_url": "https://example.com/image.jpg",
  "category": "Company News",
  "tag_id": "uuid-of-tag",
  "socials": {
    "facebook": "https://facebook.com/post",
    "twitter": "https://twitter.com/post"
  },
  "source_link": "https://source.com/article",
  "cta_plan": "plan_id",
  "status": "active"
}
```

### Update News Post
```
PUT /api/news/{id}
Authorization: Bearer {token}
```

### Toggle News Status
```
PATCH /api/news/{id}/toggle-status
Authorization: Bearer {token}
```

### Delete News Post
```
DELETE /api/news/{id}
Authorization: Bearer {token}
```

---

## CSR Campaigns

### List All CSR Campaigns
```
GET /api/csr?page=1&limit=10&status=active
Authorization: Bearer {token}
```

### Get Single CSR Campaign
```
GET /api/csr/{id}
Authorization: Bearer {token}
```

### Create CSR Campaign
```
POST /api/csr
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Community Health Outreach",
  "description": "Campaign description...",
  "cover_image_url": "https://example.com/image.jpg",
  "short_desc_one": "Short description one",
  "short_desc_two": "Short description two",
  "content_blocks": [ ... ],
  "status": "active",
  "seo_title": "SEO Title",
  "seo_description": "SEO Description",
  "seo_keywords": "keyword1, keyword2"
}
```

### Update CSR Campaign
```
PUT /api/csr/{id}
Authorization: Bearer {token}
```

### Toggle CSR Status
```
PATCH /api/csr/{id}/toggle-status
Authorization: Bearer {token}
```

### Delete CSR Campaign
```
DELETE /api/csr/{id}
Authorization: Bearer {token}
```

---

## FAQs

### List All FAQs
```
GET /api/faqs?category=general
Authorization: Bearer {token}
```

| Query Param | Type   | Default | Description                    |
|-------------|--------|---------|--------------------------------|
| category    | string | all     | Filter by category             |

### Get Single FAQ
```
GET /api/faqs/{id}
Authorization: Bearer {token}
```

### Create FAQ
```
POST /api/faqs
Authorization: Bearer {token}
Content-Type: application/json

{
  "category": "general",
  "question": "What is IHMS?",
  "answer": "IHMS stands for International Health Management Services..."
}
```

### Update FAQ
```
PUT /api/faqs/{id}
Authorization: Bearer {token}
```

### Delete FAQ
```
DELETE /api/faqs/{id}
Authorization: Bearer {token}
```

---

## Partners

### List All Partners
```
GET /api/partners?status=active
Authorization: Bearer {token}
```

### Create Partner
```
POST /api/partners
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Partner Name",
  "logoUrl": "https://example.com/logo.png",
  "status": "active"
}
```

### Update Partner
```
PUT /api/partners/{id}
Authorization: Bearer {token}
```

### Delete Partner
```
DELETE /api/partners/{id}
Authorization: Bearer {token}
```

---

## Tags

### List All Tags
```
GET /api/tags
Authorization: Bearer {token}
```

### Create Tag
```
POST /api/tags
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Health Tips"
}
```

### Update Tag
```
PUT /api/tags/{id}
Authorization: Bearer {token}
```

### Delete Tag
```
DELETE /api/tags/{id}
Authorization: Bearer {token}
```

---

## Media / File Uploads

### Upload File
```
POST /api/media/upload
Authorization: Bearer {token}
Content-Type: multipart/form-data

file: (binary file)
```

**Response (201):**
```json
{
  "status": "success",
  "message": "File uploaded successfully",
  "data": {
    "id": "uuid",
    "filename": "uuid.jpg",
    "original_name": "photo.jpg",
    "mime_type": "image/jpeg",
    "size": 123456,
    "url": "http://localhost:4000/uploads/uuid.jpg",
    "created_at": "2026-01-01 00:00:00"
  }
}
```

### List Media Files
```
GET /api/media?page=1&limit=20
Authorization: Bearer {token}
```

### Delete Media File
```
DELETE /api/media/{id}
Authorization: Bearer {token}
```

---

## Health Check

```
GET /api/health
```

**Response (200):**
```json
{
  "status": "success",
  "data": {
    "status": "ok",
    "timestamp": "2026-01-01T00:00:00+01:00",
    "version": "1.0.0"
  }
}
```

---

## Error Codes

| Status Code | Description                |
|-------------|----------------------------|
| 200         | Success                    |
| 201         | Created                    |
| 400         | Bad Request                |
| 401         | Unauthorized (invalid/expired token) |
| 404         | Resource not found         |
| 422         | Validation error           |
| 500         | Internal server error      |

## Authentication

All protected routes require a Bearer token in the Authorization header:

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

The token is obtained from the `/api/auth/login` endpoint and expires after 1 hour (configurable via `JWT_EXPIRY` in `.env`).