> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vchata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Content Controller

> Content creation, management, and social media synchronization API endpoints

# Content Controller

The Content Controller provides comprehensive content management capabilities including social media content creation, synchronization, analytics, and bio link management for the VChata platform.

## Base Path

```
/content
```

## Overview

This controller enables complete content lifecycle management:

* 📝 **Content Creation** - Create and manage social media content posts
* 🔄 **Live Data Sync** - Real-time synchronization with social media platforms
* 📊 **Content Analytics** - Performance tracking and insights
* 🔗 **Bio Link Management** - Create and manage bio links
* 🎯 **Attribution Tracking** - Track content performance and lead generation
* 📈 **Performance Optimization** - AI-powered content recommendations

## Authentication & Authorization

* 🔐 All endpoints require valid JWT authentication token
* 🏢 All operations are scoped to the user's current organization
* 👥 Organization membership required for all operations

## Content Management

### Create Content Post

<RequestExample>
  ```http theme={null}
  POST /content/org_abc123/posts
  Authorization: Bearer <token>
  Content-Type: application/json

  {
    "socialAccountId": "social_123",
    "platform": "FACEBOOK",
    "content": "Check out our amazing new product! 🚀 #innovation #tech",
    "scheduledAt": "2024-01-20T10:00:00Z",
    "tags": ["product", "launch", "innovation"],
    "keyword": "new-product-2024",
    "utmSource": "social_media",
    "utmMedium": "post",
    "utmCampaign": "product_launch"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "contentPost": {
      "id": "post_123",
      "organizationId": "org_abc123",
      "socialAccountId": "social_123",
      "platform": "FACEBOOK",
      "content": "Check out our amazing new product! 🚀 #innovation #tech",
      "scheduledAt": "2024-01-20T10:00:00Z",
      "tags": ["product", "launch", "innovation"],
      "keyword": "new-product-2024",
      "utmSource": "social_media",
      "utmMedium": "post",
      "utmCampaign": "product_launch",
      "status": "SCHEDULED",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "message": "Content post created successfully"
  }
  ```
</ResponseExample>

**Description**: Creates a new content post for social media platforms with scheduling and tracking capabilities.

<ParamField path="body" type="object">
  <Expandable title="Request Body">
    <ParamField path="socialAccountId" type="string" required>
      ID of the social media account to post to
    </ParamField>

    <ParamField path="platform" type="string" required>
      Social media platform (FACEBOOK, INSTAGRAM, TIKTOK, etc.)
    </ParamField>

    <ParamField path="content" type="string" required>
      Content text to post
    </ParamField>

    <ParamField path="scheduledAt" type="string">
      ISO 8601 timestamp for scheduled posting
    </ParamField>

    <ParamField path="tags" type="array">
      Array of tags for categorization
    </ParamField>

    <ParamField path="keyword" type="string">
      Keyword for tracking and attribution
    </ParamField>

    <ParamField path="utmSource" type="string">
      UTM source parameter for tracking
    </ParamField>

    <ParamField path="utmMedium" type="string">
      UTM medium parameter for tracking
    </ParamField>

    <ParamField path="utmCampaign" type="string">
      UTM campaign parameter for tracking
    </ParamField>
  </Expandable>
</ParamField>

### Get Content Posts

<RequestExample>
  ```http theme={null}
  GET /content/org_abc123/posts?platform=FACEBOOK&includeLiveData=true&page=1&limit=10
  Authorization: Bearer <token>
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "contentPosts": [
      {
        "id": "post_123",
        "organizationId": "org_abc123",
        "socialAccountId": "social_123",
        "platform": "FACEBOOK",
        "content": "Check out our amazing new product! 🚀 #innovation #tech",
        "platformPostId": "123456789",
        "url": "https://facebook.com/posts/123456789",
        "scheduledAt": "2024-01-20T10:00:00Z",
        "publishedAt": "2024-01-20T10:00:00Z",
        "tags": ["product", "launch", "innovation"],
        "keyword": "new-product-2024",
        "status": "PUBLISHED",
        "liveMetrics": {
          "likes": 150,
          "comments": 25,
          "shares": 12,
          "clicks": 45,
          "reach": 1250,
          "impressions": 2100
        },
        "socialAccount": {
          "id": "social_123",
          "platform": "FACEBOOK",
          "name": "Acme Corp Facebook"
        },
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-20T10:05:00Z"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "limit": 10,
      "hasMore": false
    },
    "message": "Content posts retrieved successfully"
  }
  ```
</ResponseExample>

**Description**: Retrieves content posts with optional filtering and live data synchronization.

<ParamField path="query" type="object">
  <Expandable title="Query Parameters">
    <ParamField path="socialAccountId" type="string">
      Filter by social account ID
    </ParamField>

    <ParamField path="platform" type="string">
      Filter by platform (FACEBOOK, INSTAGRAM, TIKTOK, etc.)
    </ParamField>

    <ParamField path="tags" type="string">
      Filter by tags (comma-separated)
    </ParamField>

    <ParamField path="keyword" type="string">
      Filter by exact keyword match
    </ParamField>

    <ParamField path="search" type="string">
      Search in content text
    </ParamField>

    <ParamField path="dateFrom" type="string">
      Filter posts from date (ISO 8601)
    </ParamField>

    <ParamField path="dateTo" type="string">
      Filter posts to date (ISO 8601)
    </ParamField>

    <ParamField path="includeLiveData" type="boolean">
      Include live metrics from social platforms
    </ParamField>

    <ParamField path="page" type="number">
      Page number for pagination (default: 1)
    </ParamField>

    <ParamField path="limit" type="number">
      Number of items per page (default: 10, max: 100)
    </ParamField>
  </Expandable>
</ParamField>

### Update Content Post

<RequestExample>
  ```http theme={null}
  PATCH /content/org_abc123/posts/post_123
  Authorization: Bearer <token>
  Content-Type: application/json

  {
    "content": "Updated content with new information! 🚀 #innovation #tech #updated",
    "tags": ["product", "launch", "innovation", "updated"],
    "scheduledAt": "2024-01-21T10:00:00Z"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "contentPost": {
      "id": "post_123",
      "content": "Updated content with new information! 🚀 #innovation #tech #updated",
      "tags": ["product", "launch", "innovation", "updated"],
      "scheduledAt": "2024-01-21T10:00:00Z",
      "updatedAt": "2024-01-15T15:30:00Z"
    },
    "message": "Content post updated successfully"
  }
  ```
</ResponseExample>

**Description**: Updates an existing content post with new information.

### Delete Content Post

<RequestExample>
  ```http theme={null}
  DELETE /content/org_abc123/posts/post_123
  Authorization: Bearer <token>
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "message": "Content post deleted successfully"
  }
  ```
</ResponseExample>

**Description**: Permanently deletes a content post from the system.

## Bio Link Management

### Create Bio Link

<RequestExample>
  ```http theme={null}
  POST /bio/org_abc123/links
  Authorization: Bearer <token>
  Content-Type: application/json

  {
    "title": "Summer Sale 2024",
    "description": "Check out our amazing summer deals!",
    "url": "https://acme.com/summer-sale",
    "imageUrl": "https://acme.com/images/summer-banner.jpg",
    "buttonText": "Shop Now",
    "utmSource": "bio_link",
    "utmMedium": "social",
    "utmCampaign": "summer_2024",
    "isActive": true
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "bioLink": {
      "id": "bio_link_123",
      "organizationId": "org_abc123",
      "title": "Summer Sale 2024",
      "description": "Check out our amazing summer deals!",
      "url": "https://acme.com/summer-sale",
      "shortUrl": "https://vchata.link/summer2024",
      "imageUrl": "https://acme.com/images/summer-banner.jpg",
      "buttonText": "Shop Now",
      "utmSource": "bio_link",
      "utmMedium": "social",
      "utmCampaign": "summer_2024",
      "isActive": true,
      "clickCount": 0,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "message": "Bio link created successfully"
  }
  ```
</ResponseExample>

**Description**: Creates a new bio link for social media profiles.

<ParamField path="body" type="object">
  <Expandable title="Request Body">
    <ParamField path="title" type="string" required>
      Title of the bio link
    </ParamField>

    <ParamField path="description" type="string">
      Description of the bio link
    </ParamField>

    <ParamField path="url" type="string" required>
      Destination URL
    </ParamField>

    <ParamField path="imageUrl" type="string">
      Optional image URL for the link
    </ParamField>

    <ParamField path="buttonText" type="string">
      Text for the call-to-action button
    </ParamField>

    <ParamField path="utmSource" type="string">
      UTM source parameter
    </ParamField>

    <ParamField path="utmMedium" type="string">
      UTM medium parameter
    </ParamField>

    <ParamField path="utmCampaign" type="string">
      UTM campaign parameter
    </ParamField>

    <ParamField path="isActive" type="boolean">
      Whether the bio link is active (default: true)
    </ParamField>
  </Expandable>
</ParamField>

### Get Bio Links

<RequestExample>
  ```http theme={null}
  GET /bio/org_abc123/links?isActive=true&page=1&limit=10
  Authorization: Bearer <token>
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "bioLinks": [
      {
        "id": "bio_link_123",
        "title": "Summer Sale 2024",
        "description": "Check out our amazing summer deals!",
        "url": "https://acme.com/summer-sale",
        "shortUrl": "https://vchata.link/summer2024",
        "imageUrl": "https://acme.com/images/summer-banner.jpg",
        "buttonText": "Shop Now",
        "isActive": true,
        "clickCount": 45,
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-20T15:30:00Z"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "limit": 10,
      "hasMore": false
    },
    "message": "Bio links retrieved successfully"
  }
  ```
</ResponseExample>

**Description**: Retrieves bio links with optional filtering.

### Update Bio Link

<RequestExample>
  ```http theme={null}
  PATCH /bio/org_abc123/links/bio_link_123
  Authorization: Bearer <token>
  Content-Type: application/json

  {
    "title": "Updated Summer Sale 2024",
    "description": "New and improved summer deals!",
    "url": "https://acme.com/summer-sale-v2",
    "buttonText": "Shop Now - Updated"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "bioLink": {
      "id": "bio_link_123",
      "title": "Updated Summer Sale 2024",
      "description": "New and improved summer deals!",
      "url": "https://acme.com/summer-sale-v2",
      "buttonText": "Shop Now - Updated",
      "updatedAt": "2024-01-20T16:00:00Z"
    },
    "message": "Bio link updated successfully"
  }
  ```
</ResponseExample>

**Description**: Updates an existing bio link.

### Delete Bio Link

<RequestExample>
  ```http theme={null}
  DELETE /bio/org_abc123/links/bio_link_123
  Authorization: Bearer <token>
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "message": "Bio link deleted successfully"
  }
  ```
</ResponseExample>

**Description**: Permanently deletes a bio link.

## Content Analytics

### Get Content Analytics

<RequestExample>
  ```http theme={null}
  GET /content/org_abc123/analytics?dateFrom=2024-01-01&dateTo=2024-01-31&platform=FACEBOOK
  Authorization: Bearer <token>
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "analytics": {
      "overview": {
        "totalPosts": 25,
        "totalEngagement": 1250,
        "totalReach": 15000,
        "totalClicks": 450,
        "averageEngagementRate": 8.3,
        "averageClickThroughRate": 3.0
      },
      "platforms": [
        {
          "platform": "FACEBOOK",
          "posts": 15,
          "engagement": 850,
          "reach": 10000,
          "clicks": 300
        },
        {
          "platform": "INSTAGRAM",
          "posts": 10,
          "engagement": 400,
          "reach": 5000,
          "clicks": 150
        }
      ],
      "topPerformingPosts": [
        {
          "id": "post_123",
          "content": "Check out our amazing new product! 🚀",
          "engagement": 150,
          "reach": 1250,
          "clicks": 45
        }
      ],
      "engagementTrends": [
        {
          "date": "2024-01-01",
          "engagement": 50,
          "reach": 600
        },
        {
          "date": "2024-01-02",
          "engagement": 75,
          "reach": 800
        }
      ]
    },
    "message": "Content analytics retrieved successfully"
  }
  ```
</ResponseExample>

**Description**: Retrieves comprehensive content performance analytics.

<ParamField path="query" type="object">
  <Expandable title="Query Parameters">
    <ParamField path="dateFrom" type="string">
      Start date for analytics (ISO 8601)
    </ParamField>

    <ParamField path="dateTo" type="string">
      End date for analytics (ISO 8601)
    </ParamField>

    <ParamField path="platform" type="string">
      Filter by platform (FACEBOOK, INSTAGRAM, TIKTOK, etc.)
    </ParamField>

    <ParamField path="socialAccountId" type="string">
      Filter by social account ID
    </ParamField>

    <ParamField path="tags" type="string">
      Filter by tags (comma-separated)
    </ParamField>

    <ParamField path="metrics" type="string">
      Specific metrics to include (comma-separated)
    </ParamField>
  </Expandable>
</ParamField>

### Get Content Performance

<RequestExample>
  ```http theme={null}
  GET /content/org_abc123/posts/post_123/performance
  Authorization: Bearer <token>
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "performance": {
      "postId": "post_123",
      "content": "Check out our amazing new product! 🚀",
      "metrics": {
        "likes": 150,
        "comments": 25,
        "shares": 12,
        "clicks": 45,
        "reach": 1250,
        "impressions": 2100,
        "engagementRate": 12.0,
        "clickThroughRate": 3.6
      },
      "demographics": {
        "ageGroups": {
          "18-24": 25,
          "25-34": 45,
          "35-44": 20,
          "45-54": 10
        },
        "genders": {
          "male": 60,
          "female": 40
        }
      },
      "timing": {
        "bestPerformingHour": 14,
        "bestPerformingDay": "Tuesday",
        "averageEngagementTime": 25
      },
      "attribution": {
        "leadsGenerated": 5,
        "conversions": 2,
        "revenue": 250.00
      }
    },
    "message": "Content performance retrieved successfully"
  }
  ```
</ResponseExample>

**Description**: Retrieves detailed performance metrics for a specific content post.

## Content Status Values

* **DRAFT** - Content is being created/edited
* **SCHEDULED** - Content is scheduled for future posting
* **PUBLISHED** - Content has been posted to social media
* **FAILED** - Content posting failed
* **DELETED** - Content has been deleted from social media

## Error Responses

### Common Errors

<ResponseExample status="400">
  ```json theme={null}
  {
    "success": false,
    "statusCode": 400,
    "message": [
      "content is required",
      "socialAccountId must be a valid UUID",
      "platform must be one of: FACEBOOK, INSTAGRAM, TIKTOK"
    ],
    "error": "Bad Request"
  }
  ```
</ResponseExample>

<ResponseExample status="404">
  ```json theme={null}
  {
    "success": false,
    "statusCode": 404,
    "message": "Content post not found or you don't have access",
    "error": "Not Found"
  }
  ```
</ResponseExample>

<ResponseExample status="409">
  ```json theme={null}
  {
    "success": false,
    "statusCode": 409,
    "message": "Content already exists with this keyword",
    "error": "Conflict"
  }
  ```
</ResponseExample>

<ResponseExample status="502">
  ```json theme={null}
  {
    "success": false,
    "statusCode": 502,
    "message": "Social media platform temporarily unavailable",
    "error": "Bad Gateway"
  }
  ```
</ResponseExample>

## Advanced Features

### Live Data Synchronization

The content controller includes advanced live data synchronization capabilities:

* **Real-time Metrics** - Fetch live engagement metrics from social platforms
* **Auto-Sync** - Automatically sync new posts from social media platforms
* **Conflict Resolution** - Handle conflicts between local and platform data
* **Batch Processing** - Efficient batch synchronization for large datasets

### Content Attribution

Track how content generates leads and conversions:

* **UTM Tracking** - Complete UTM parameter support for attribution
* **Lead Generation** - Link content interactions to lead creation
* **Conversion Tracking** - Track revenue and conversions from content
* **ROI Analysis** - Calculate return on investment for content campaigns

### Performance Optimization

* **Caching** - Intelligent caching for frequently accessed content
* **Rate Limiting** - Respect platform API rate limits
* **Batch Operations** - Efficient batch processing for bulk operations
* **Error Recovery** - Automatic retry mechanisms for failed operations

### Multi-Platform Support

* **Cross-Platform Content** - Create content for multiple platforms simultaneously
* **Platform-Specific Features** - Leverage platform-specific capabilities
* **Unified Analytics** - Consolidated analytics across all platforms
* **Consistent Tracking** - Unified tracking and attribution across platforms