1. GET /v1/social/facebook/pages

Retrieve a list of Facebook Pages connected to the authenticated user.

Headers: Authorization: Bearer <API_KEY>

Response:

{
  "success": true,
  "pages": [
    {
      "id": "123456789",
      "name": "My Business Page",
      "category": "Company",
      "access_token": "EAAG...",
      "profile_picture_url": "https://..."
    }
  ]
}

2. GET /v1/social/facebook/photos

Retrieve all photos from a specific Facebook Page.

Query Parameters: page_id (string, required)

Response:

{
  "success": true,
  "photos": [
    {
      "id": "PHOTO_ID",
      "url": "https://facebook.com/photo/...",
      "created_time": "2025-05-25T14:00:00Z"
    }
  ]
}

3. GET /v1/social/facebook/videos

Retrieve all videos from a specific Facebook Page.

Query Parameters: page_id (string, required)

Response:

{
  "success": true,
  "videos": [
    {
      "id": "VIDEO_ID",
      "title": "Summer Campaign 2025",
      "url": "https://facebook.com/video/...",
      "created_time": "2025-05-20T12:00:00Z"
    }
  ]
}

4. POST /v1/social/facebook/publish

Publish a standard post with text and optional media.

Request Body:

{
  "page_id": "123456789",
  "message": "We're launching something new!",
  "media_url": "https://example.com/image.jpg" // optional
}

Response:

{
  "success": true,
  "post_id": "FB_POST_ID"
}

5. POST /v1/social/facebook/publish-carousel

Publish a carousel post (multiple images).

Request Body:

{
  "page_id": "123456789",
  "message": "Check out our new offers!",
  "media_urls": [
    "https://example.com/img1.jpg",
    "https://example.com/img2.jpg"
  ]
}

Response:

{
  "success": true,
  "carousel_id": "FB_CAROUSEL_ID"
}

6. POST /v1/social/facebook/publish-video

Publish a video post with title and description.

Request Body:

{
  "page_id": "123456789",
  "video_url": "https://example.com/video.mp4",
  "title": "Product Demo",
  "description": "Watch our new product in action."
}

7. POST /v1/social/facebook/comment

Post a comment on an existing Facebook post.

Request Body:

{
  "page_id": "123456789",
  "post_id": "POST_ID",
  "message": "This is awesome!"
}

8. POST /v1/social/facebook/reply

Reply to a comment on a Facebook post.

Request Body:

{
  "page_id": "123456789",
  "comment_id": "COMMENT_ID",
  "message": "Thanks for the feedback!"
}

9. POST /v1/social/facebook/like

Like a specific post.

Request Body:

{
  "page_id": "123456789",
  "post_id": "POST_ID"
}

10. POST /v1/social/facebook/message

Send a direct message to a user via Facebook Messenger.

Request Body:

{
  "page_id": "123456789",
  "recipient_id": "USER_ID",
  "message": "Hi there! How can we help you today?"
}

11. GET /v1/social/facebook/stats

Retrieve detailed analytics for a Facebook Page.

Query Parameters: page_id (string, required)

Response:

{
  "success": true,
  "stats": {
    "followers": 24800,
    "reach": 172300,
    "engagement_rate": 5.1,
    "impressions": 342000
  }
}

12. DELETE /v1/social/facebook/post/{post_id}

Delete a Facebook post.

Path Parameter: post_id (string)

Request Body:

{
  "page_id": "123456789"
}

Response:

{
  "success": true,
  "message": "Post deleted successfully."
}

1. GET /v1/social/facebook/ads/accounts

Retrieve all ad accounts connected to the authenticated user.

Headers: Authorization: Bearer <API_KEY>

Response:

{
  "success": true,
  "accounts": [
    {
      "id": "act_1234567890",
      "name": "Main Business Account",
      "currency": "USD",
      "status": "ACTIVE"
    }
  ]
}

2. GET /v1/social/facebook/ads/campaigns

Fetch all ad campaigns under a specific Ad Account.

Query Parameters: ad_account_id (required)

Response:

{
  "success": true,
  "campaigns": [
    {
      "id": "238123456789",
      "name": "Spring Promo",
      "status": "PAUSED",
      "objective": "LINK_CLICKS",
      "created_time": "2025-03-10T12:30:00Z"
    }
  ]
}

3. POST /v1/social/facebook/ads/campaigns

Create a new ad campaign.

Request Body:

{
  "ad_account_id": "act_1234567890",
  "name": "New Campaign 2025",
  "objective": "CONVERSIONS",
  "status": "PAUSED"
}

Response:

{
  "success": true,
  "campaign_id": "238987654321"
}

4. POST /v1/social/facebook/ads/adsets

Create an Ad Set under a campaign.

Request Body:

{
  "ad_account_id": "act_1234567890",
  "campaign_id": "238987654321",
  "name": "Ad Set 1",
  "daily_budget": 1500,
  "start_time": "2025-06-01T00:00:00Z",
  "end_time": "2025-06-10T00:00:00Z",
  "billing_event": "IMPRESSIONS",
  "optimization_goal": "REACH",
  "targeting": {
    "geo_locations": {
      "countries": ["US", "CA"]
    },
    "age_min": 18,
    "age_max": 45
  }
}

5. POST /v1/social/facebook/ads/creatives

Create a new ad creative (text + media).

Request Body:

{
  "ad_account_id": "act_1234567890",
  "name": "Ad Creative 1",
  "title": "Amazing Offer",
  "body": "Get 50% OFF today!",
  "image_url": "https://example.com/image.jpg",
  "link_url": "https://your-landing-page.com"
}

6. POST /v1/social/facebook/ads/ads

Launch a full ad using an ad set and a creative.

Request Body:

{
  "ad_account_id": "act_1234567890",
  "adset_id": "120392123",
  "creative_id": "2342321",
  "name": "Ad Test Launch",
  "status": "PAUSED"
}

7. GET /v1/social/facebook/ads/stats

Retrieve performance metrics for an Ad, Ad Set, or Campaign.

Query Parameters: ad_account_id (required), level = ad | adset | campaign (required), entity_id (required)

Response:

{
  "success": true,
  "stats": {
    "impressions": 34231,
    "clicks": 239,
    "ctr": 0.69,
    "spend": 72.50,
    "conversions": 21
  }
}

8. DELETE /v1/social/facebook/ads/{ad_id}

Delete a specific ad.

Path Parameter: ad_id (string)

Body:

{
  "ad_account_id": "act_1234567890"
}

Response:

{
  "success": true,
  "message": "Ad deleted successfully."
}

9. PATCH /v1/social/facebook/ads/status

Update status (ACTIVE / PAUSED / DELETED) of an ad, ad set, or campaign.

Request Body:

{
  "ad_account_id": "act_1234567890",
  "entity_id": "238987654321",
  "level": "campaign",
  "status": "ACTIVE"
}

Response:

{
  "success": true,
  "message": "Status updated."
}

1. GET /v1/social/instagram/accounts

Returns a list of connected Instagram Business accounts.

Headers: Authorization: Bearer <API_KEY>

Response:

{
  "success": true,
  "accounts": [
    {
      "id": "17841400000000000",
      "username": "@mybrand",
      "profile_picture_url": "https://instagram.com/...",
      "biography": "We build tech that matters.",
      "followers_count": 10230
    }
  ]
}

Error Example:

{
  "success": false,
  "error_code": "INSTAGRAM/ACCOUNT_NOT_FOUND",
  "message": "No Instagram Business account is linked to the provided Facebook Page."
}

2. GET /v1/social/instagram/media

Get all published media (posts, reels, IGTV) of an account.

Query Parameters: account_id (string, required)

Response:

{
  "success": true,
  "media": [
    {
      "id": "17895500000000000",
      "type": "IMAGE",
      "media_url": "https://...",
      "caption": "Launch day!",
      "timestamp": "2025-05-25T12:00:00Z"
    }
  ]
}

Error Example:

{
  "success": false,
  "error_code": "INSTAGRAM/MEDIA_ACCESS_DENIED",
  "message": "The provided token does not have permission to access media data."
}

3. POST /v1/social/instagram/publish-post

Publish a standard image post.

Request Body:

{
  "account_id": "17841400000000000",
  "image_url": "https://example.com/image.jpg",
  "caption": "Introducing our new feature!"
}

Response:

{
  "success": true,
  "media_id": "17895500000000000"
}

Error Example:

{
  "success": false,
  "error_code": "INSTAGRAM/INVALID_IMAGE",
  "message": "The image URL provided is not accessible or invalid."
}

4. POST /v1/social/instagram/publish-reel

Publish a video Reel.

Request Body:

{
  "account_id": "17841400000000000",
  "video_url": "https://example.com/video.mp4",
  "caption": "Behind the scenes!"
}

Error Example:

{
  "success": false,
  "error_code": "INSTAGRAM/REEL_UPLOAD_FAILED",
  "message": "Video could not be processed. Ensure format is MP4 and size < 100MB."
}

5. POST /v1/social/instagram/comment

Post a comment on an Instagram post.

Request Body:

{
  "account_id": "17841400000000000",
  "media_id": "17895500000000000",
  "message": "Awesome work!"
}

Response:

{
  "success": true,
  "comment_id": "17938482736282901"
}

6. POST /v1/social/instagram/reply

Reply to a comment.

Request Body:

{
  "account_id": "17841400000000000",
  "comment_id": "17938482736282901",
  "message": "Thanks a lot!"
}

7. POST /v1/social/instagram/message

Send a Direct Message (DM) to a user (only available for business inbox).

Request Body:

{
  "account_id": "17841400000000000",
  "recipient_id": "USER_ID",
  "message": "Hi there! Let us know how we can help."
}

Error Example:

{
  "success": false,
  "error_code": "INSTAGRAM/DM_RESTRICTED",
  "message": "This account does not have access to Instagram Messaging API."
}

8. GET /v1/social/instagram/stats

Retrieve statistics for a given post.

Query Parameters: media_id (string, required)

Response:

{
  "success": true,
  "stats": {
    "likes": 134,
    "comments": 17,
    "shares": 9,
    "reach": 4300,
    "impressions": 7100
  }
}

9. DELETE /v1/social/instagram/media/{media_id}

Delete a specific media (image or video) from Instagram.

Path Parameter: media_id (string)

Body:

{
  "account_id": "17841400000000000"
}

Response:

{
  "success": true,
  "message": "Media deleted successfully."
}

Error Example:

{
  "success": false,
  "error_code": "INSTAGRAM/DELETE_FORBIDDEN",
  "message": "You can only delete media that was created by this app."
}

1. GET /v1/social/instagram/ads/accounts

List all available ad accounts that can be used to run Instagram Ads.

Response:

{
  "success": true,
  "accounts": [
    {
      "id": "act_1234567890",
      "name": "Main IG Ad Account",
      "currency": "USD",
      "status": "ACTIVE"
    }
  ]
}

Error Example:

{
  "success": false,
  "error_code": "INSTAGRAM_ADS/NO_ACCOUNTS_FOUND",
  "message": "No eligible ad accounts found for the authenticated user."
}

2. GET /v1/social/instagram/ads/campaigns

Retrieve all ad campaigns targeting Instagram.

Query Parameters: ad_account_id (required)

Response:

{
  "success": true,
  "campaigns": [
    {
      "id": "238123456789",
      "name": "IG Awareness 2025",
      "objective": "REACH",
      "status": "ACTIVE"
    }
  ]
}

3. POST /v1/social/instagram/ads/campaigns

Create a new Instagram-specific ad campaign.

Request Body:

{
  "ad_account_id": "act_1234567890",
  "name": "IG Campaign 2025",
  "objective": "POST_ENGAGEMENT",
  "status": "PAUSED"
}

4. POST /v1/social/instagram/ads/adsets

Create an ad set targeted to Instagram users.

Request Body:

{
  "ad_account_id": "act_1234567890",
  "campaign_id": "238123456789",
  "name": "IG Audience - US Teens",
  "daily_budget": 2000,
  "billing_event": "IMPRESSIONS",
  "optimization_goal": "ENGAGED_USERS",
  "start_time": "2025-06-01T00:00:00Z",
  "end_time": "2025-06-10T00:00:00Z",
  "targeting": {
    "platforms": ["instagram"],
    "publisher_platforms": ["instagram"],
    "geo_locations": {
      "countries": ["US"]
    },
    "age_min": 13,
    "age_max": 19
  }
}

Error Example:

{
  "success": false,
  "error_code": "INSTAGRAM_ADS/TARGETING_INVALID",
  "message": "Targeting settings must include Instagram as a platform."
}

5. POST /v1/social/instagram/ads/creatives

Create a new Instagram ad creative.

Request Body:

{
  "ad_account_id": "act_1234567890",
  "name": "IG Creative - Launch",
  "image_url": "https://example.com/image.jpg",
  "caption": "Try our new features!",
  "link_url": "https://yourwebsite.com"
}

Response:

{
  "success": true,
  "creative_id": "120392933231"
}

6. POST /v1/social/instagram/ads/ads

Create a complete ad using a creative and ad set.

Request Body:

{
  "ad_account_id": "act_1234567890",
  "adset_id": "2383929301",
  "creative_id": "120392933231",
  "name": "IG Ad Launch",
  "status": "PAUSED"
}

7. GET /v1/social/instagram/ads/stats

Retrieve ad performance metrics for a campaign, ad set, or individual ad.

Query Parameters: ad_account_id (required), level: campaign | adset | ad (required), entity_id: (required)

Response:

{
  "success": true,
  "stats": {
    "impressions": 34000,
    "clicks": 460,
    "reach": 22000,
    "ctr": 1.35,
    "spend": 98.00,
    "conversions": 39
  }
}

8. PATCH /v1/social/instagram/ads/status

Update the status of an Instagram campaign, ad set, or ad.

Request Body:

{
  "ad_account_id": "act_1234567890",
  "entity_id": "2383929301",
  "level": "ad",
  "status": "ACTIVE"
}

9. DELETE /v1/social/instagram/ads/{ad_id}

Delete an Instagram ad by ID.

Path Parameter: ad_id

Request Body:

{
  "ad_account_id": "act_1234567890"
}

Response:

{
  "success": true,
  "message": "Ad successfully deleted."
}

1. GET /v1/social/tiktok/accounts

List connected TikTok accounts with basic metadata.

Response:

{
  "success": true,
  "accounts": [
    {
      "id": "7133829237812000002",
      "username": "@mybrand",
      "verified": true,
      "avatar_url": "https://...",
      "follower_count": 105000
    }
  ]
}

Error Example:

{
  "success": false,
  "error_code": "TIKTOK/ACCOUNT_NOT_CONNECTED",
  "message": "No TikTok account is currently linked to this user."
}

2. GET /v1/social/tiktok/videos

Retrieve all videos from a TikTok account.

Query Parameters: user_id (required)

Response:

{
  "success": true,
  "videos": [
    {
      "id": "7293847328832",
      "title": "Behind the scenes",
      "video_url": "https://...",
      "cover_image_url": "https://...",
      "created_at": "2025-05-20T14:00:00Z"
    }
  ]
}

3. POST /v1/social/tiktok/publish-video

Upload and publish a video to TikTok.