Posts Management API

Author: Josh S. Sakweli, Backend Lead Team Last Updated: 2025-12-11
Version: v1.0

Base URL: https://api.nexgate.com/api/v1

Short Description: The Posts Management API provides comprehensive social media posting functionality including creating posts, polls, quote posts, drafts management, media attachments, commerce integrations, collaboration features, and engagement interactions (likes, bookmarks, reposts, comments). This API enables users to create rich content with privacy controls and scheduled publishing.

Hints:

All endpoints require authentication via Bearer token unless specified
Draft posts follow a "one draft at a time" rule - publish or discard before creating new
Posts support text content, media (images/videos), polls, and commerce attachments
Privacy settings control visibility, comment permissions, and repost permissions
Collaborative posts require accepted invitations from collaborators
Pagination is 1-indexed (page=1 for first page), default size is 20 items
Poll votes can be changed if poll allows it (allowVoteChange setting)

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-09-23T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field	Type	Description
`success`	boolean	Always `true` for successful operations, `false` for errors
`httpStatus`	string	HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
`message`	string	Human-readable message describing the operation result
`action_time`	string	ISO 8601 timestamp of when the response was generated
`data`	object/string	Response payload for success, error details for failures

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

GET - GET - Green (Safe, read-only operations)
POST - POST - Blue (Create new resources)
PUT - PUT - Yellow (Update/replace entire resource)
DELETE - DELETE - Red (Remove resources)

Common Response Structure for POST/PUT Operations

Most POST and PUT operations return a PostResponse object. For brevity, this documentation references the detailed PostResponse structure defined below instead of repeating it for each endpoint.

Standard Success Response for Post Creation/Update:

{
  "success": true,
  "httpStatus": "OK",
  "message": "[Operation-specific message]",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    // PostResponse object - see "PostResponse Structure" section below
  }
}

PostResponse Structure

This is the standard response structure returned by most post-related endpoints:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "author": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "userName": "john_doe",
    "firstName": "John",
    "lastName": "Doe",
    "profilePictureUrl": "https://cdn.nexgate.com/profiles/john_doe.jpg",
    "isVerified": true
  },
  "content": "Check out this amazing product! @jane_doe #shopping",
  "contentParsed": {
    "text": "Check out this amazing product! @jane_doe #shopping",
    "entities": [
      {
        "type": "MENTION",
        "text": "@jane_doe",
        "startIndex": 33,
        "endIndex": 42,
        "user": {
          "id": "987e6543-e21b-12d3-a456-426614174999",
          "userName": "jane_doe",
          "firstName": "Jane",
          "lastName": "Doe",
          "profilePictureUrl": "https://cdn.nexgate.com/profiles/jane_doe.jpg"
        }
      },
      {
        "type": "HASHTAG",
        "text": "#shopping",
        "startIndex": 43,
        "endIndex": 52,
        "hashtag": "shopping"
      }
    ]
  },
  "postType": "REGULAR",
  "status": "PUBLISHED",
  "media": [
    {
      "id": "media-123",
      "mediaType": "IMAGE",
      "originalUrl": "https://cdn.nexgate.com/posts/image1.jpg",
      "thumbnailUrl": "https://cdn.nexgate.com/posts/image1_thumb.jpg",
      "placeholderBase64": "base64-string-here",
      "width": 1920,
      "height": 1080,
      "order": 1,
      "imageTags": []
    }
  ],
  "attachments": {
    "products": [],
    "shops": [],
    "events": [],
    "buyTogetherGroups": [],
    "installmentPlans": [],
    "externalLink": null
  },
  "collaboration": {
    "isCollaborative": false,
    "collaborators": [],
    "byline": null
  },
  "privacySettings": {
    "visibility": "PUBLIC",
    "whoCanComment": "EVERYONE",
    "whoCanRepost": "EVERYONE",
    "hideLikesCount": false,
    "hideCommentsCount": false
  },
  "engagement": {
    "likesCount": 0,
    "commentsCount": 0,
    "repostsCount": 0,
    "quotesCount": 0,
    "bookmarksCount": 0,
    "sharesCount": 0,
    "viewsCount": 0,
    "canLike": true,
    "canComment": true,
    "canRepost": true,
    "canShare": true
  },
  "userInteraction": {
    "hasLiked": false,
    "hasBookmarked": false,
    "hasReposted": false,
    "hasCommented": false,
    "hasViewed": false
  },
  "createdAt": "2025-12-11T10:30:45",
  "publishedAt": "2025-12-11T10:30:45",
  "scheduledAt": null
}

Endpoints

1. Create Post

Purpose: Create a new post (draft or scheduled) with optional content, media, poll, attachments, and collaboration

Endpoint: POST {base_url}/e-social/posts

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Request JSON Sample:

{
  "content": "Excited to share my latest project! @john_doe check this out #coding",
  "postType": "REGULAR",
  "media": [
    {
      "mediaType": "IMAGE",
      "mediaUrl": "https://cdn.nexgate.com/uploads/image1.jpg",
      "placeholderBase64": "base64-string",
      "width": 1920,
      "height": 1080
    }
  ],
  "privacySettings": {
    "visibility": "PUBLIC",
    "whoCanComment": "EVERYONE",
    "whoCanRepost": "EVERYONE",
    "hideLikesCount": false,
    "hideCommentsCount": false
  },
  "scheduledAt": null
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
content	string	No	Post text content	Max: 5000 characters
postType	string	Yes	Type of post	enum: REGULAR, POLL
media	array	No	Array of media objects (images/videos)	Max: 10 items
media[].mediaType	string	Yes (if media provided)	Type of media	enum: IMAGE, VIDEO
media[].mediaUrl	string	Yes (if media provided)	URL of the media file	Valid URL format
media[].placeholderBase64	string	No	BlurHash or base64 placeholder
media[].width	integer	No	Media width in pixels
media[].height	integer	No	Media height in pixels
media[].duration	integer	No	Video duration in seconds	Required for videos
poll	object	No	Poll configuration	Required if postType is POLL
poll.title	string	Yes (if poll provided)	Poll question/title
poll.description	string	No	Additional poll description
poll.options	array	Yes (if poll provided)	Array of poll options	Min: 2, Max: 10
poll.options[].optionText	string	Yes	Text for the poll option
poll.options[].optionImageUrl	string	No	Optional image for the option
poll.allowMultipleVotes	boolean	No	Allow selecting multiple options	Default: false
poll.isAnonymous	boolean	No	Hide voter identities	Default: true
poll.allowVoteChange	boolean	No	Allow users to change their vote	Default: true
poll.expiresAt	string	No	Poll expiration datetime	ISO 8601 format, must be future
attachments	object	No	Commerce attachments
attachments.productIds	array	No	Array of product UUIDs to attach	Max: 10
attachments.shopIds	array	No	Array of shop UUIDs to attach	Max: 5
attachments.eventIds	array	No	Array of event UUIDs to attach	Max: 3
attachments.buyTogetherGroupIds	array	No	Array of group purchase UUIDs
attachments.installmentPlanIds	array	No	Array of installment plan UUIDs
attachments.externalLink	object	No	External link object
attachments.externalLink.url	string	Yes (if externalLink provided)	URL to attach	Valid URL format
collaboration	object	No	Collaboration settings
collaboration.collaboratorIds	array	No	Array of user UUIDs to invite	Max: 5
privacySettings	object	No	Privacy configuration
privacySettings.visibility	string	No	Post visibility level	enum: PUBLIC, FOLLOWERS, MENTIONED, PRIVATE. Default: PUBLIC
privacySettings.whoCanComment	string	No	Comment permission level	enum: EVERYONE, FOLLOWERS, MENTIONED, DISABLED. Default: EVERYONE
privacySettings.whoCanRepost	string	No	Repost permission level	enum: EVERYONE, FOLLOWERS, DISABLED. Default: EVERYONE
privacySettings.hideLikesCount	boolean	No	Hide like count from others	Default: false
privacySettings.hideCommentsCount	boolean	No	Hide comment count from others	Default: false
scheduledAt	string	No	Schedule post for future publication	ISO 8601 format, must be future

Success Response: Returns standard PostResponse structure (see "PostResponse Structure" section above)

Success Response Message: "Post created successfully"

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "You already have a draft post",
  "action_time": "2025-12-11T10:30:45",
  "data": "You already have a draft post. Please update or publish your existing draft before creating a new one."
}

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: Already have a draft post, invalid post data, or validation errors
401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
422 UNPROCESSABLE_ENTITY: Validation errors with detailed field information
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Bad Request - Existing Draft (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "You already have a draft post",
  "action_time": "2025-12-11T10:30:45",
  "data": "You already have a draft post. Please update or publish your existing draft before creating a new one."
}

Validation Error - Content Too Long (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "content": "Content exceeds maximum length of 5000 characters"
  }
}

Validation Error - Invalid Poll (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "poll.options": "Poll must have at least 2 options"
  }
}

2. Publish Draft Post

Purpose: Publish the current user's draft post

Endpoint: POST {base_url}/e-social/posts/publish

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Success Response: Returns standard PostResponse structure with status changed to PUBLISHED

Success Response Message: "Post published successfully"

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: No draft found, draft incomplete, or only draft posts can be published
401 UNAUTHORIZED: Authentication issues
500 INTERNAL_SERVER_ERROR: Unexpected server errors

3. Delete Post

Purpose: Soft delete a post (marks as deleted, doesn't remove from database)

Endpoint: DELETE {base_url}/e-social/posts/{postId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
postId	string	Yes	UUID of the post to delete	Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Post deleted successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": null
}

Success Response Fields:

Field	Description
data	Always null for this endpoint

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: Can only delete your own posts
401 UNAUTHORIZED: Authentication issues
404 NOT_FOUND: Post not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

4. Get Post by ID

Purpose: Retrieve a single post by its ID with full details

Endpoint: GET {base_url}/e-social/posts/{postId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
postId	string	Yes	UUID of the post to retrieve	Must be valid UUID format

Success Response: Returns standard PostResponse structure

Success Response Message: "Post retrieved successfully"

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues
404 NOT_FOUND: Post not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

5. Get Published Posts

Purpose: Retrieve all published posts with pagination (for discovery/explore feed)

Endpoint: GET {base_url}/e-social/posts

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-indexed)	Min: 1	1
size	integer	No	Number of items per page	Min: 1, Max: 100	20

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Posts retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": [
    {
      // PostResponse object
    },
    {
      // PostResponse object
    }
  ]
}

Success Response Fields:

Field	Description
data	Array of PostResponse objects

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues
500 INTERNAL_SERVER_ERROR: Unexpected server errors

6. Get Posts by Author

Purpose: Retrieve all posts from a specific author with pagination

Endpoint: GET {base_url}/e-social/posts/author/{authorId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
authorId	string	Yes	UUID of the author	Must be valid UUID format

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-indexed)	Min: 1	1
size	integer	No	Number of items per page	Min: 1, Max: 100	20

Success Response: Returns array of PostResponse objects

Success Response Message: "Posts retrieved successfully"

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues
404 NOT_FOUND: Author not found
500 INTERNAL_SERVER_ERROR: Unexpected server errors

7. Get My Scheduled Posts

Purpose: Retrieve all scheduled posts for the authenticated user

Endpoint: GET {base_url}/e-social/posts/scheduled

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Success Response: Returns array of PostResponse objects with status SCHEDULED

Success Response Message: "Scheduled posts retrieved successfully"

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues
500 INTERNAL_SERVER_ERROR: Unexpected server errors

8. Get My Current Draft

Purpose: Retrieve the authenticated user's current draft post

Endpoint: GET {base_url}/e-social/posts/draft

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Success Response: Returns standard PostResponse structure with status DRAFT, or null if no draft exists

Success Response Message: "Draft retrieved successfully"

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues
500 INTERNAL_SERVER_ERROR: Unexpected server errors

9. Discard Draft

Purpose: Delete the current draft post permanently

Endpoint: DELETE {base_url}/e-social/posts/draft

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Draft discarded successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": null
}

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: No draft found or can only discard your own draft
401 UNAUTHORIZED: Authentication issues
500 INTERNAL_SERVER_ERROR: Unexpected server errors

10. Update Draft

Purpose: Update content, media, or privacy settings of the current draft

Endpoint: PUT {base_url}/e-social/posts

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Request JSON Sample:

{
  "content": "Updated post content",
  "media": [
    {
      "mediaType": "IMAGE",
      "mediaUrl": "https://cdn.nexgate.com/uploads/new_image.jpg",
      "width": 1920,
      "height": 1080
    }
  ],
  "privacySettings": {
    "visibility": "FOLLOWERS",
    "whoCanComment": "FOLLOWERS"
  }
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
content	string	No	Updated post text content	Max: 5000 characters
media	array	No	Updated media array	Max: 10 items
privacySettings	object	No	Updated privacy settings

Success Response: Returns standard PostResponse structure with updated values

Success Response Message: "Draft updated successfully"

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: No draft found, can only update your own posts, or only draft posts can be updated
401 UNAUTHORIZED: Authentication issues
422 UNPROCESSABLE_ENTITY: Validation errors
500 INTERNAL_SERVER_ERROR: Unexpected server errors

11-20. Draft Commerce Attachments (Attach/Remove Products, Shops, Events, Groups, Plans)

For brevity, these endpoints follow the same pattern:

Attach Endpoints: POST {base_url}/e-social/posts/draft/attach-{type}/{id}

/draft/attach-product/{productId}
/draft/attach-shop/{shopId}
/draft/attach-event/{eventId}
/draft/attach-group/{groupId}
/draft/attach-plan/{planId}

Remove Endpoints: DELETE {base_url}/e-social/posts/draft/remove-{type}/{id}

/draft/remove-product/{productId}
/draft/remove-shop/{shopId}
/draft/remove-event/{eventId}
/draft/remove-group/{groupId}
/draft/remove-plan/{planId}

All return standard PostResponse structure. Success messages follow pattern: "{Type} attached/removed to/from draft successfully"

21. Update Draft Content Only

Purpose: Update only the text content of the current draft

Endpoint: PUT {base_url}/e-social/posts/content

Request Body: Plain text string (not JSON object)

Success Response: Returns standard PostResponse structure

Success Response Message: "Draft content updated successfully"

22. Update Draft Media Only

Purpose: Update only the media attachments of the current draft

Endpoint: PUT {base_url}/e-social/posts/media

Request Body: Array of MediaRequest objects

Success Response: Returns standard PostResponse structure

Success Response Message: "Media added to draft successfully"

23. Update Draft Privacy Settings Only

Purpose: Update only the privacy settings of the current draft

Endpoint: PUT {base_url}/e-social/posts/privacy

Request Body: PrivacySettingsRequest object

Success Response: Returns standard PostResponse structure

Success Response Message: "Privacy settings updated successfully"

24. Update Draft Collaboration

Purpose: Update collaborator invitations for the current draft

Endpoint: PUT {base_url}/e-social/posts/collaboration

Request Body: CollaborationRequest object with collaboratorIds array

Success Response: Returns standard PostResponse structure

Success Response Message: "Collaboration settings updated successfully"

25. Accept Collaboration

Purpose: Accept a collaboration invitation on a published post

Endpoint: POST {base_url}/e-social/posts/{postId}/collaboration/accept

Success Response: Returns standard PostResponse structure

Success Response Message: "Collaboration accepted successfully"

26. Decline Collaboration

Purpose: Decline a collaboration invitation on a published post

Endpoint: POST {base_url}/e-social/posts/{postId}/collaboration/decline

Success Response: Returns standard PostResponse structure

Success Response Message: "Collaboration declined successfully"

27. Remove Collaborator

Purpose: Remove a collaborator from a published post (author or self only)

Endpoint: DELETE {base_url}/e-social/posts/{postId}/collaborators/{collaboratorId}

Success Response Message: "Collaborator removed successfully"

28. Create Quote Post

Purpose: Create a new post that quotes an existing post

Endpoint: POST {base_url}/e-social/posts/quote/{quotedPostId}

Request Body: CreateQuotePostRequest object (similar to CreatePostRequest but without poll support)

Success Response: Returns standard PostResponse structure with quotedPost field populated

Success Response Message: "Quote post created successfully"

Interaction Endpoints (29-38)

Like Post: POST {base_url}/e-social/posts/{postId}/like

Unlike Post: DELETE {base_url}/e-social/posts/{postId}/like

Bookmark Post: POST {base_url}/e-social/posts/{postId}/bookmark

Unbookmark Post: DELETE {base_url}/e-social/posts/{postId}/bookmark

Repost Post: POST {base_url}/e-social/posts/{postId}/repost

Optional request body: {"comment": "Optional comment when reposting"}

Unrepost Post: DELETE {base_url}/e-social/posts/{postId}/repost

Record View: POST {base_url}/e-social/posts/{postId}/view

Get My Bookmarks: GET {base_url}/e-social/posts/bookmarks

Get My Reposts: GET {base_url}/e-social/posts/my-reposts

Get User Reposts: GET {base_url}/e-social/posts/users/{userId}/reposts

All interaction endpoints return data: null except GET endpoints which return paginated PostResponse arrays.

Poll Endpoints (39-43)

39. Vote on Poll

Purpose: Cast a vote on a poll post

Endpoint: POST {base_url}/e-social/posts/{postId}/vote

Request JSON Sample:

{
  "optionIds": ["option-uuid-1", "option-uuid-2"]
}

Success Response Message: "Vote recorded successfully"

40. Remove Vote

Purpose: Remove your vote from a poll

Endpoint: DELETE {base_url}/e-social/posts/{postId}/vote

Success Response Message: "Vote removed successfully"

41. Get Poll Results

Purpose: Get detailed poll results including vote counts and percentages

Endpoint: GET {base_url}/e-social/posts/{postId}/poll-results

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Poll results retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "pollId": "poll-uuid",
    "title": "What's your favorite programming language?",
    "description": "Choose your top pick",
    "totalVotes": 150,
    "allowMultipleVotes": false,
    "isAnonymous": true,
    "allowVoteChange": true,
    "expiresAt": "2025-12-15T10:30:45",
    "hasExpired": false,
    "userHasVoted": true,
    "options": [
      {
        "optionId": "option-uuid-1",
        "optionText": "Python",
        "optionImageUrl": null,
        "optionOrder": 1,
        "votesCount": 75,
        "percentage": 50.0,
        "userVoted": true
      },
      {
        "optionId": "option-uuid-2",
        "optionText": "JavaScript",
        "optionImageUrl": null,
        "optionOrder": 2,
        "votesCount": 50,
        "percentage": 33.3,
        "userVoted": false
      },
      {
        "optionId": "option-uuid-3",
        "optionText": "Java",
        "optionImageUrl": null,
        "optionOrder": 3,
        "votesCount": 25,
        "percentage": 16.7,
        "userVoted": false
      }
    ]
  }
}

42. Get Poll Voters

Purpose: Get list of users who voted for a specific poll option (author/collaborators only, non-anonymous polls only)

Endpoint: GET {base_url}/e-social/posts/{postId}/poll-voters/{optionId}

Success Response: Returns array of VoterInfo objects

Success Response Message: "Voters retrieved successfully"

Comment Endpoints (43-52)

43. Create Comment

Purpose: Create a comment or reply on a post

Endpoint: POST {base_url}/e-social/posts/{postId}/comments

Request JSON Sample:

{
  "content": "Great post! @john_doe you should check this out",
  "parentCommentId": null
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
content	string	Yes	Comment text	Min: 1, Max: 2000 characters
parentCommentId	string	No	UUID of parent comment for replies	Must be valid UUID if provided

Success Response: Returns CommentResponse object

Success Response Message: "Comment created successfully"

Remaining Comment Endpoints (following same pattern):

Get Comments: GET {base_url}/e-social/posts/{postId}/comments

Get Comment: GET {base_url}/e-social/posts/comments/{commentId}

Get Replies: GET {base_url}/e-social/posts/comments/{commentId}/replies

Update Comment: PUT {base_url}/e-social/posts/comments/{commentId}

Delete Comment: DELETE {base_url}/e-social/posts/comments/{commentId}

Pin Comment: POST {base_url}/e-social/posts/{postId}/comments/{commentId}/pin

Unpin Comment: DELETE {base_url}/e-social/posts/comments/{commentId}/pin

Like Comment: POST {base_url}/e-social/posts/comments/{commentId}/like

Unlike Comment: DELETE {base_url}/e-social/posts/comments/{commentId}/like

Quick Reference Guide

Common HTTP Status Codes

200 OK: Successful GET/POST/PUT/DELETE request
400 Bad Request: Invalid request data or business rule violation
401 Unauthorized: Authentication required/failed
404 Not Found: Resource not found
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server error

Authentication

Bearer Token: Include Authorization: Bearer your_token in headers

Data Format Standards

Dates: Use ISO 8601 format (2025-12-11T14:30:00Z)
IDs: UUID format (e.g., 550e8400-e29b-41d4-a716-446655440000)
Pagination: 1-indexed pages (page=1 for first page), default size=20

Post Type Values

REGULAR: Standard text/media post
POLL: Poll post with voting options

Post Status Values

DRAFT: Unpublished draft
SCHEDULED: Scheduled for future publication
PUBLISHED: Live and visible
DELETED: Soft deleted

Visibility Levels

PUBLIC: Anyone can see
FOLLOWERS: Only followers can see
MENTIONED: Only mentioned users can see
PRIVATE: Only author can see

Permission Levels

EVERYONE: All users
FOLLOWERS: Only followers
MENTIONED: Only mentioned users (for comments)
DISABLED: Feature disabled