Blogs

Blog Routes

List Blogs

GET /api/blogs

Query Parameters (optional):

• author=me — Fetch blogs written by the authenticated user.
• author=<uid> — Fetch public blogs of a specific user.
• search=<query> — Search blogs by title (case insensitive).

Behavior:

• Responses are paginated, 20 per page
• No author param → Return all public blogs (sorted by most recent).
• author=me → Return all blogs of the authenticated user (private + friends + public).
• author=<uid> → Return only public blogs by that user.
• search=<query> → Search blogs by title (case insensitive). Can be combined with author parameter.

Response Format:

{
  "success": true,
  "message": "Blogs fetched successfully",
  "data": {
    "blogs": [ /* Array of blog objects */ ]
  }
}

Sample response:

{
    "success": true,
    "message": "Blogs fetched successfully",
    "data": {
        "blogs": [
            {
                "_id": "6847133861841477d982ac22",
                "user": {
                    "_id": "6843292c5cc2e9ee0b9bc0a9",
                    "username": "test",
                    "displayName": "TestUser",
                    "avatar": "Dummy avatar"
                },
                "title": "My Second Blog!",
                "content": "## This is blog content",
                "visibility": "public",
                "spoilerAlert": false,
                "genres": [],
                "createdAt": "2025-06-09T17:00:40.091Z",
                "updatedAt": "2025-06-09T17:00:40.091Z",
                "__v": 0
            },
            {
                "_id": "68470ca92df9925ccd743b78",
                "user": {
                    "_id": "6843292c5cc2e9ee0b9bc0a9",
                    "username": "test",
                    "displayName": "TestUser",
                    "avatar": "Dummy avatar"
                },
                "title": "My First Blog!",
                "content": "## This is my first blog",
                "visibility": "public",
                "spoilerAlert": false,
                "genres": [],
                "createdAt": "2025-06-09T16:32:41.983Z",
                "updatedAt": "2025-06-09T16:32:41.983Z",
                "__v": 0
            }
        ]
    }
}

---

Get a Blog by ID

GET /api/blogs/:id

Behavior:

• Return the blog if:

  • It is public, OR
  • It belongs to the authenticated user

Response Format:

{
  "success": true,
  "message": "Blog fetched successfully",
  "data": {
    "blog": { /* Blog details */ }
  }
}

Sample response (success):

{
    "success": true,
    "message": "Blog fetched successfully",
    "data": {
        "blog": {
            "_id": "6847144261841477d982ac2f",
            "user": {
                "_id": "6843292c5cc2e9ee0b9bc0a9",
                "username": "test",
                "displayName": "TestUser",
                "avatar": "Dummy avatar"
            },
            "title": "My First Blog!",
            "content": "## This is my first blog\n**Im so excited!**\n\nList item:\n- item 1\n- item 2\n- item 3",
            "visibility": "public",
            "spoilerAlert": false,
            "genres": [],
            "createdAt": "2025-06-09T17:05:06.094Z",
            "updatedAt": "2025-06-09T17:05:06.094Z",
            "__v": 0
        }
    }
}

Sample response (no permission):

{
    "success": true,
    "message": "You do not have access to this blog"
}

---

Create a Blog

POST /api/blogs

Input: req.body.data

{
  "title": "Reflections on Reading", // required
  "content": "Books change lives...", // required
  "visibility": "public", // defaults to "public"
  "spoilerAlert": false, // required
  "genres": ["Drama", "Biography"] // optional
}

Behavior:

• Authenticated user creates a blog post.
• visibility can be public, friends, or private.
• blog content must be Markdown string
• genres must be chosen from predefined GENRES.

Response Format:

{
  "success": true,
  "message": "Blog created successfully",
  "data": {
    "blog": { /* Newly created blog object */ }
  }
}

Sample response:

{
    "success": true,
    "message": "Blog created successfully",
    "data": {
        "blog": {
            "user": {
                "_id": "6843292c5cc2e9ee0b9bc0a9",
                "username": "test",
                "displayName": "TestUser",
                "avatar": "Dummy avatar"
            },
            "title": "My First Blog!",
            "content": "## This is my first blog\n**Im so excited!**\n\nList item:\n- item 1\n- item 2\n- item 3",
            "visibility": "public",
            "spoilerAlert": false,
            "genres": [],
            "_id": "6847144261841477d982ac2f",
            "createdAt": "2025-06-09T17:05:06.094Z",
            "updatedAt": "2025-06-09T17:05:06.094Z",
            "__v": 0
        }
    }
}

---

Update a Blog

PATCH /api/blogs/:id

Input: req.body.data Any one or multiple of the following fields can be updated:

{
  "title": "Updated Title",
  "content": "Updated content...",
  "visibility": "friends",
  "spoilerAlert": true,
  "genres": ["Mystery"]
}

Behavior:

• Only the owner can update their blog.
• Fields like title, content, visibility, genres, and spoilerAlert can be updated.

Response Format:

{
  "success": true,
  "message": "Blog updated successfully",
  "data": {
    "blog": { /* Updated blog */ }
  }
}

Sample response:

{
    "success": true,
    "message": "Blog updated successfully",
    "data": {
        "blog": {
            "_id": "6847133861841477d982ac22",
            "user": {
                "_id": "6843292c5cc2e9ee0b9bc0a9",
                "username": "test",
                "displayName": "TestUser",
                "avatar": "Dummy avatar"
            },
            "title": "My Second Blog!",
            "content": "## This is so much fun\n**I love writing blogs\n\nThis line is newly added!**",
            "visibility": "public",
            "spoilerAlert": false,
            "genres": [],
            "createdAt": "2025-06-09T17:00:40.091Z",
            "updatedAt": "2025-06-09T17:21:56.138Z",
            "__v": 0
        }
    }
}

---

Delete a Blog

DELETE /api/blogs/:id

Behavior:

• Only the owner can delete their blog.

Response:

{
  "success": true,
  "message": "Blog deleted successfully"
}

Sample response:

{
    "success": true,
    "message": "Blog deleted successfully",
    "data": {}
}