API Documentation

Reset Schedule

• Monthly Plans: Usage resets on your signup anniversary day each month
• Annual Plans: Usage resets on your signup anniversary date each year
• Free Users: Automatic reset based on signup date
• Paid Users: Reset triggered by Stripe billing webhooks

What's Tracked

• Uploads: Each successful post creation (drafts don't count) - resets with billing cycle
• Profiles: Total number of profiles you currently have - decreases when you delete profiles
• Last Reset: Timestamp of your last usage reset (uploads only)

Upload Limit Exceeded

{
  "error": "Upload limit reached. Your Free plan allows 10 uploads per month. You have used 10.",
  "planName": "Free",
  "limit": 10,
  "current": 10,
  "billingPeriod": "monthly"
}

Profile Limit Exceeded

{
  "error": "Profile limit reached. Your basic plan allows 10 profiles. You currently have 10.",
  "planName": "basic",
  "limit": 10,
  "current": 10,
  "details": {
    "resource": "profiles",
    "plan": "basic",
    "currentUsage": 10,
    "limit": 10,
    "window": "total"
  }
}

1. Create a Profile

2. Connect Social Accounts

3. Schedule a Post

GET /v1/profiles

Get all profiles for your account.

Response

{
  "profiles": [
    {
      "_id": "profile_id",
      "name": "Personal Brand",
      "description": "My personal accounts", 
      "color": "#ffeda0",
      "isDefault": true,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /v1/profiles

Create a new profile. Subject to plan limits.

Request Body

{
  "name": "Business Account",
  "description": "Company social media",
  "color": "#4ade80"
}

Response Status Codes

• 201 - Profile created successfully
• 400 - Invalid request data or profile name already exists
• 401 - Invalid API key
• 403 - Profile limit reached for your plan
• 404 - User not found

PUT /v1/profiles/[profileId]

Update an existing profile.

DELETE /v1/profiles/[profileId]

Delete a profile. Cannot delete profiles with connected accounts.

GET /v1/usage-stats

Get current usage statistics for your account.

Response

{
  "planName": "Professional",
  "billingPeriod": "yearly",
  "limits": {
    "uploads": -1,
    "profiles": 50,
    "postsPerDayPerAccount": 8
  },
  "usage": {
    "uploads": 847,
    "profiles": 12,
    "lastReset": "2024-01-01T00:00:00.000Z"
  },
  "canUpload": true,
  "canCreateProfile": true
}

Response Fields

• limits.uploads - Upload limit (-1 = unlimited)
• limits.profiles - Profile limit
• usage.uploads - Current period uploads
• usage.profiles - Total profiles created
• canUpload - Whether you can create more posts
• canCreateProfile - Whether you can create more profiles

GET /v1/posts

Retrieve a list of your scheduled and published posts with pagination.

Query Parameters

• page - Page number (default: 1)
• limit - Posts per page (default: 10, max: 100)
• status - Filter by status (draft, scheduled, published, failed)
• platform - Filter by platform

POST /v1/posts

Create and schedule a new post across multiple social media platforms. Subject to upload limits.

Request Body

{
  "content": "Your post content here",
  "profileId": "profile_id",
  "platforms": ["twitter", "instagram", "linkedin"],
  "scheduledFor": "2024-01-01T12:00:00",
  "timezone": "America/New_York",
  "publishNow": false,
  "isDraft": false,
  "visibility": "public|private|unlisted",
  "mediaItems": [
    {
      "type": "image|video|gif",
      "url": "media_url_from_/v1/media",
      "filename": "optional_filename"
    }
  ]
}

Response Status Codes

• 201 - Post published successfully to all platforms
• 207 - Multi-Status: Some platforms succeeded, others failed
• 400 - Invalid request data
• 401 - Invalid API key

GET /v1/posts/[postId]

Get details of a specific post by ID.

PUT /v1/posts/[postId]

Update a post. Only draft and scheduled posts can be edited.

Request Body

Same structure as POST /v1/posts, all fields are optional:

{
  "content": "Updated post content",
  "scheduledFor": "2024-01-01T15:00:00",
  "timezone": "America/New_York",
  "platforms": ["twitter", "linkedin"],
  "isDraft": false,
  "publishNow": false,
  "mediaItems": [...]
}

DELETE /v1/posts/[postId]

Delete a post. Published posts cannot be deleted. All other statuses (draft, scheduled, publishing, failed, cancelled) can be deleted.

POST /v1/posts/[postId]/retry

Retry publishing a failed post. Only failed posts can be retried.

POST /v1/media

Upload media files (images/videos) for use in posts.

Request

Content-Type: multipart/form-data

GET /v1/accounts

Get connected social media accounts, optionally filtered by profile.

Query Parameters

• profileId - Filter accounts by profile ID (optional)

Response

{
  "accounts": [
    {
      "_id": "account_id",
      "profileId": "profile_id",
      "platform": "instagram",
      "username": "your_username",
      "displayName": "Your Display Name",
      "profilePicture": "https://...",
      "isActive": true,
      "tokenExpiresAt": "2024-12-31T23:59:59Z",
      "permissions": ["posts:write", "posts:read"]
    }
  ]
}

GET /v1/connect/[platform]

Initiate OAuth connection for a platform to a specific profile.

Query Parameters

• profileId - Profile ID to connect the account to (required)
• redirect_url - Custom URL to redirect to after OAuth completion (optional)

Custom Redirects

By default, users are redirected to the dashboard after connecting an account. Use redirect_url to redirect to your own application instead.

DELETE /v1/accounts/[accountId]

Disconnect a social media account from its profile.

GET /v1/connect/facebook/select-page

Get available Facebook pages for selection during connection process.

Query Parameters

• profileId - Profile ID to connect the page to (required)
• tempToken - Temporary OAuth token from Facebook (required)

Response

{
  "pages": [
    {
      "id": "page_id_123",
      "name": "My Business Page",
      "access_token": "page_access_token_...",
      "category": "Business",
      "tasks": ["MANAGE", "CREATE_CONTENT"]
    }
  ]
}

POST /v1/connect/facebook/select-page

Connect a specific Facebook page to a profile.

Request Body

{
  "profileId": "profile_id_123",
  "pageId": "page_id_456",
  "tempToken": "facebook_temp_token...",
  "userProfile": {
    "id": "user_facebook_id",
    "name": "User Name",
    "profilePicture": "https://..."
  }
}

Response

{
  "message": "Facebook page connected successfully",
  "account": {
    "platform": "facebook",
    "username": "My Business Page",
    "displayName": "My Business Page",
    "isActive": true,
    "selectedPageName": "My Business Page"
  }
}

PUT /v1/accounts/[accountId]/facebook-page

Update which Facebook page an existing account should post to.

Request Body

{
  "selectedPageId": "new_page_id_789"
}

Instagram Content Types

{
  "platform": "instagram",
  "contentType": "post",
  "media": ["image_url_1", "image_url_2"],
  "caption": "Your post caption here"
}

{
  "platform": "instagram",
  "contentType": "story",
  "media": ["image_url_1"],
  "caption": "Optional story caption"
}

YouTube Content Types

{
  "platform": "youtube",
  "media": ["video_url"],
  "title": "Your video title",
  "description": "Your video description"
}

{
  "platform": "youtube",
  "media": ["vertical_video_url"],
  "title": "Your short video title",
  "description": "Your description #Shorts"
}