Posts Management API

Author: JoshJosh, S. Sakweli,Lead 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

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

Behavior:

• Creates a post with status DRAFT (unless scheduledAt is provided, then SCHEDULED)
• Enforces "one draft at a time" rule - user must publish or discard existing draft first
• Automatically parses @mentions, $shop tags, and #hashtags from content
• Validates all attached products, shops, events exist and are active
• Sends collaboration invitations to specified users via notifications
• For scheduled posts, validates scheduledAt is at least 5 minutes in the future
• Media files must already be uploaded to file service before creating post
• Collaborative posts remain in PENDING status until all invitees accept/reject

Business Rules:

1. Draft System: Only one draft allowed per user at a time
2. Content Requirements: Either content text OR media OR poll must be provided (not all optional)
3. Poll Requirements: If postType is POLL, poll object with 2-10 options is required
4. Media Limits: Maximum 10 media items per post
5. Commerce Limits: Max 10 products, 5 shops, 3 events per post
6. Collaboration Limits: Maximum 5 collaborators per post
7. Scheduling Rules: Scheduled time must be at least 5 minutes in future, max 6 months ahead
8. Mention Extraction: System automatically detects and links @username and $shopname mentions
9. Hashtag Indexing: All #hashtags automatically indexed for search and trending
10. Privacy Inheritance: MENTIONED visibility requires at least one @mention in content

Request Headers:

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:

Validation Notes:

• At least one of: content, media, or poll must be provided
• If postType is POLL, content is optional but poll object is required
• Media files must be pre-uploaded to file service and URLs must be from approved CDN domains
• All UUIDs (products, shops, events, users) are validated for existence and status
• Mentions (@username, $shopname) and hashtags (#tag) are automatically extracted from content
• MENTIONED visibility requires at least one @mention in content
• Scheduled posts cannot be in the past; minimum 5 minutes buffer required
• Collaborative posts send real-time notifications to all invited users
• External links are validated for protocol (http/https only) and reachability

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"
  }
}

Validation Error - Empty Post (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Post must have content, media, or poll",
  "action_time": "2025-12-11T10:30:45",
  "data": "At least one of content, media, or poll must be provided"
}

Validation Error - Invalid Product Attachment (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Product not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "Product with ID 550e8400-e29b-41d4-a716-446655440000 not found or inactive"
}

Validation Error - Scheduled Time in Past (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid scheduled time",
  "action_time": "2025-12-11T10:30:45",
  "data": "Scheduled time must be at least 5 minutes in the future"
}

Validation Error - Blocked Collaborator (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Cannot collaborate with blocked user",
  "action_time": "2025-12-11T10:30:45",
  "data": "User 770e8400-e29b-41d4-a716-446655440001 has blocked you or you have blocked them"
}

Use Case Examples:

Example 1: Simple Text Post

{
  "content": "Just launched my new product! Check it out at nexgate.com/myshop",
  "postType": "REGULAR"
}

Result: Creates a PUBLIC draft post with text only, no attachments.

Example 2: Product Showcase Post

{
  "content": "New arrivals! 🎉 Amazing deals on electronics. $TechWorld #shopping #deals",
  "postType": "REGULAR",
  "media": [
    {
      "mediaType": "IMAGE",
      "mediaUrl": "https://cdn.nexgate.com/uploads/product1.jpg",
      "width": 1920,
      "height": 1080
    }
  ],
  "attachments": {
    "productIds": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002"],
    "shopIds": ["660e8400-e29b-41d4-a716-446655440003"]
  }
}

Result: Creates draft with image, attaches 2 products and 1 shop, extracts $TechWorld mention and #shopping/#deals hashtags.

Example 3: Poll Post

{
  "content": "What feature should we build next? Vote below! 👇",
  "postType": "POLL",
  "poll": {
    "title": "Next Feature Priority",
    "description": "Help us decide what to build for Q1 2026",
    "options": [
      {"optionText": "Dark Mode"},
      {"optionText": "Video Upload"},
      {"optionText": "Live Streaming"},
      {"optionText": "Advanced Analytics"}
    ],
    "allowMultipleVotes": true,
    "isAnonymous": false,
    "allowVoteChange": true,
    "expiresAt": "2025-12-25T23:59:59Z"
  }
}

Result: Creates poll allowing multiple votes, non-anonymous (voters visible), votes can be changed, expires Dec 25.

Example 4: Scheduled Collaborative Event Post

{
  "content": "Excited to announce our tech conference! @john_doe and I are hosting. Join us! 🚀 #TechConf2026",
  "postType": "REGULAR",
  "attachments": {
    "eventIds": ["880e8400-e29b-41d4-a716-446655440004"]
  },
  "collaboration": {
    "collaboratorIds": ["770e8400-e29b-41d4-a716-446655440001"]
  },
  "scheduledAt": "2025-12-20T08:00:00Z"
}

Result: Creates scheduled post for Dec 20, attaches event, sends collaboration invite to john_doe, extracts @john_doe mention and #TechConf2026 hashtag.

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

Behavior:

• Finds user's current draft post (status = DRAFT)
• Changes post status from DRAFT to PUBLISHED
• Sets publishedAt timestamp to current time
• Sends notifications to all mentioned users (@username, $shopname)
• For collaborative posts, only publishes if all collaborators have accepted
• Increments engagement counters for all attached products/shops/events
• Triggers feed distribution to all followers
• No request body required - system automatically finds the user's draft

Business Rules:

1. Draft Requirement: User must have exactly one draft post
2. Collaboration Status: All invited collaborators must have accepted (status = ACCEPTED)
3. Content Validation: Draft must pass all content validation rules before publishing
4. Attachment Validation: All attached products/shops/events must still be active/valid
5. Scheduled Posts: Cannot publish a scheduled post (status = SCHEDULED) using this endpoint
6. Feed Distribution: Published posts immediately appear in followers' feeds
7. Notification Triggers: Sends notifications to @mentioned users and collaborators
8. Engagement Initialization: All engagement counters (likes, comments, etc.) start at 0

Validation Checks on Publish:

• Draft exists and belongs to current user
• All collaborators have accepted (if collaborative post)
• All attached products are still ACTIVE
• All attached shops are still VERIFIED
• All attached events are still PUBLISHED
• Content still meets length requirements (5000 chars)
• Media URLs still valid and accessible
• Poll configuration valid (if poll post)

Request Headers:

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
• 403 FORBIDDEN: Collaborative post pending approval from collaborators
• 404 NOT_FOUND: No draft post found for user
• 422 UNPROCESSABLE_ENTITY: Draft validation failed (invalid attachments, etc.)
• 500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

No Draft Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "No draft post found",
  "action_time": "2025-12-11T10:30:45",
  "data": "You don't have a draft post to publish"
}

Pending Collaborator Approval (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Cannot publish collaborative post",
  "action_time": "2025-12-11T10:30:45",
  "data": "Waiting for collaborator acceptance. 2 of 3 collaborators have accepted."
}

Invalid Attached Product (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Invalid product attachment",
  "action_time": "2025-12-11T10:30:45",
  "data": "Product 550e8400-e29b-41d4-a716-446655440001 is no longer active and must be removed before publishing"
}

Use Case Examples:

Example 1: Simple Draft Publish

POST /e-social/posts/publish

User has draft: "Hello world! This is my first post"
Result: Draft published, appears in followers' feeds, status = PUBLISHED, publishedAt set to current time

Example 2: Collaborative Draft Publish (All Accepted)

POST /e-social/posts/publish

User has draft with 2 collaborators
Both collaborators have accepted (status = ACCEPTED)
Result: Draft published, all 3 authors credited, appears on all 3 profiles, notifications sent

Example 3: Collaborative Draft Publish (Pending Approval)

POST /e-social/posts/publish

User has draft with 3 collaborators
Only 2 have accepted, 1 still pending
Result: Error 403 - Cannot publish until all collaborators accept

Example 4: Draft with Product Attachment

POST /e-social/posts/publish

User has draft with attached product
Product validation checks:
- Product exists? ✓
- Product status ACTIVE? ✓
- Product belongs to active shop? ✓
Result: Draft published, product card appears in post, shop gets notification

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

Behavior:

• Performs soft delete: Sets isDeleted flag to true, doesn't remove from database
• Removes post from all users' feeds immediately
• Preserves post data for analytics and audit purposes
• All comments, likes, bookmarks remain in database but are hidden
• Decrements engagement counters for attached products/shops/events
• Sends notification to collaborators (if collaborative post)
• Post no longer appears in searches, hashtag feeds, or explore pages
• Only post author can delete their own posts (not collaborators)

Business Rules:

1. Author Only: Only the original post author can delete (collaborators cannot)
2. Soft Delete: Data retained in database with isDeleted = true
3. Irreversible: Deleted posts cannot be undeleted (would need backend intervention)
4. Cascade Hiding: Comments/likes/bookmarks hidden but not deleted
5. Analytics Preservation: Engagement data preserved for historical analytics
6. Feed Removal: Immediately removed from all feeds (home, explore, profile)
7. Notification: Collaborators notified of deletion
8. Attachment Impact: Products/shops/events lose post engagement stats

What Gets Hidden:

• Post itself (no longer visible to anyone)
• All comments and replies on the post
• All likes, bookmarks, reposts
• Post no longer appears in:
  • User's profile
  • Followers' feeds
  • Hashtag pages
  • Search results
  • Product/shop/event pages (if attached)

What Gets Preserved (in database for analytics):

• Original post content and metadata
• All engagement metrics (historical counts)
• All comments and their content
• All likes, bookmarks, and reposts
• Author and timestamp information
• Attachment relationships

Request Headers:

Path Parameters:

Success Response JSON Sample:

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

Success Response Fields:

Standard Error Types:

Application-Level Exceptions (400-499)

• 400 BAD_REQUEST: Can only delete your own posts
• 401 UNAUTHORIZED: Authentication issues
• 403 FORBIDDEN: Not the post author (collaborators cannot delete)
• 404 NOT_FOUND: Post not found or already deleted
• 500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Not Post Author (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Cannot delete post",
  "action_time": "2025-12-11T10:30:45",
  "data": "Only the post author can delete this post. Collaborators cannot delete."
}

Post Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Post not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "Post with ID 550e8400-e29b-41d4-a716-446655440000 not found or already deleted"
}

Use Case Examples:

Example 1: Delete Regular Post

DELETE /e-social/posts/550e8400-e29b-41d4-a716-446655440000

Post has: 50 likes, 10 comments, 5 reposts
Result: Post soft deleted, all engagement hidden, removed from feeds, data preserved in DB

Example 2: Delete Post with Product Attachments

DELETE /e-social/posts/660e8400-e29b-41d4-a716-446655440001

Post attached to 2 products
Result: Post deleted, product engagement counters decremented, post removed from product pages

Example 3: Collaborator Tries to Delete (Fails)

DELETE /e-social/posts/770e8400-e29b-41d4-a716-446655440002

User is collaborator, not author
Result: Error 403 - Only original author can delete collaborative posts

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

Behavior:

• Returns full post details including author info, content, media, attachments, engagement
• Respects post visibility settings (PUBLIC, FOLLOWERS, MENTIONED, PRIVATE)
• Checks if requesting user has permission to view based on privacy settings
• Includes user interaction state (hasLiked, hasBookmarked, etc.)
• For poll posts, includes user's voting status and results if visible
• Increments view counter if this is first view by this user
• Returns parsed content with @mentions, $shops, and #hashtags highlighted
• Includes collaboration info if collaborative post

Visibility Logic:

• PUBLIC: Anyone can view
• FOLLOWERS: Only followers of author can view
• MENTIONED: Only users mentioned in post (@username) can view
• PRIVATE: Only author can view

Additional Access Rules:

• Blocked users cannot view each other's posts (even if PUBLIC)
• Deleted posts (isDeleted = true) return 404 NOT_FOUND
• Scheduled posts (status = SCHEDULED) only visible to author before scheduled time
• Draft posts (status = DRAFT) only visible to author
• Collaborative posts visible to all collaborators regardless of visibility setting

Response Includes:

• Full post content with parsed entities (mentions, hashtags, shops)
• Author information with profile picture and verification status
• All media with URLs, dimensions, placeholders (BlurHash)
• All commerce attachments (products, shops, events, groups, installments)
• Collaboration details (if collaborative post)
• Privacy settings
• Engagement metrics (likes, comments, reposts counts)
• User's interaction state (liked?, bookmarked?, reposted?, etc.)
• Poll results (if poll post and user can see results)
• Creation and publication timestamps

Request Headers:

Path Parameters:

Success Response: Returns standard PostResponse structure

Success Response Message: "Post retrieved successfully"

Standard Error Types:

Application-Level Exceptions (400-499)

• 401 UNAUTHORIZED: Authentication issues
• 403 FORBIDDEN: User doesn't have permission to view this post (visibility restrictions)
• 404 NOT_FOUND: Post not foundfound, deleted, or not yet published (scheduled/draft)
• 500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Post Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Post not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "Post with ID 550e8400-e29b-41d4-a716-446655440000 not found"
}

Insufficient Permissions - Followers Only (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Cannot view this post",
  "action_time": "2025-12-11T10:30:45",
  "data": "This post is visible to followers only. Follow the author to view."
}

Blocked User (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Cannot view this post",
  "action_time": "2025-12-11T10:30:45",
  "data": "You cannot view posts from this user"
}

Use Case Examples:

Example 1: View Public Post

GET /e-social/posts/550e8400-e29b-41d4-a716-446655440000

Post visibility: PUBLIC
Result: Full post details returned, view counter incremented, engagement visible

Example 2: View Followers-Only Post (Not Following)

GET /e-social/posts/660e8400-e29b-41d4-a716-446655440001

Post visibility: FOLLOWERS
User is not following author
Result: Error 403 - Must follow author to view

Example 3: View Mentioned Post (Not Mentioned)

GET /e-social/posts/770e8400-e29b-41d4-a716-446655440002

Post visibility: MENTIONED
User not mentioned in post
Result: Error 403 - Only mentioned users can view

Example 4: View Own Draft Post

GET /e-social/posts/880e8400-e29b-41d4-a716-446655440003

Post status: DRAFT
User is post author
Result: Full post details returned with status = DRAFT

Example 5: View Collaborative Post (As Collaborator)

GET /e-social/posts/990e8400-e29b-41d4-a716-446655440004

Post visibility: PRIVATE
User is accepted collaborator
Result: Full post details returned (collaborators can always view)

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:

Query Parameters:

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:

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:

Path Parameters:

Query Parameters:

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:

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:

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:

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:

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:

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)

29. Like Post

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

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Cannot like this post",
  "action_time": "2025-12-11T10:30:45",
  "data": "You cannot interact with posts from this user"
}

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Post not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "Post with ID 550e8400-e29b-41d4-a716-446655440000 not found"
}

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

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

POST /e-social/posts/550e8400-e29b-41d4-a716-446655440000/bookmark

User sees interesting post with products attached
Bookmarks to check products later
Result: Post saved to bookmarks, appears in GET /posts/bookmarks

POST /e-social/posts/660e8400-e29b-41d4-a716-446655440001/bookmark

Post has 3 collaborators
User bookmarks for reference
Result: Post bookmarked, visible in bookmarks even if one collaborator leaves

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

{
  "comment": "This is amazing! Everyone should see this 🔥"
}

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

{
  "success": true,
  "httpStatus": "OK",
  "message": "Quote post created successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    // Returns full PostResponse for the new quote post
    // with quotedPost field containing original post
  }
}

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Cannot repost this post",
  "action_time": "2025-12-11T10:30:45",
  "data": "The author has disabled reposts for this post"
}

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Cannot repost this post",
  "action_time": "2025-12-11T10:30:45",
  "data": "Only followers can repost this post. Follow the author to repost."
}

POST /e-social/posts/550e8400-e29b-41d4-a716-446655440000/repost

Body: {} or no body

Result: Original post appears on user's profile with "reposted" badge
Appears in followers' feeds
Original author gets notification

POST /e-social/posts/660e8400-e29b-41d4-a716-446655440001/repost

Body: {
  "comment": "This is exactly what I've been saying! Great insight 🎯"
}

Result: Creates new quote post with comment
Original post embedded in quote
New post has own likes/comments
Both posts' repost counters incremented

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

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

{
  "success": true,
  "httpStatus": "OK",
  "message": "Bookmarks retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": [
    {
      // Full PostResponse object
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "Bookmarked post content...",
      // ... rest of PostResponse
    },
    {
      // Another PostResponse object
    }
  ]
}

{
  "success": true,
  "httpStatus": "OK",
  "message": "Reposts retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": [
    {
      // Full PostResponse object of reposted post
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "author": {
        // Original author info
      },
      "content": "Original post content...",
      // ... rest of PostResponse
    }
  ]
}

{
  "success": true,
  "httpStatus": "OK",
  "message": "User reposts retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": [
    {
      // Full PostResponse object of reposted post
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "author": {
        // Original author info
      },
      "content": "Original post content...",
      // ... rest of PostResponse
    }
  ]
}

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

{
  "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
      }
    ]
  }
}

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