Postifys API Reference

Publish image or Reel to a Facebook Page

Creates a native photo, Reel, or text/link feed post on a connected Facebook Page for the API key owner. Pass pageId for a specific Page, or omit it to use the default configured Page.

• text or message string, optional if a media URL or link is present.
• mediaUrls array or string URL, optional for feed posts. Required for images and Reels.
• link string URL, optional fallback for mediaUrls.
• type string, optional. Use IMAGE for native Page photos, REEL for native Facebook Reels, or FEED for text/link posts. Default is IMAGE when media is present and FEED for text-only posts.
• pageId string, optional connected Facebook Page ID.
• proxyDownload boolean, optional. When true, Postifys downloads the media to a temporary file first. Images are published through a short-lived Postifys URL. Reels are uploaded to Meta using the Facebook Reels API. Temp files are deleted after publish. Automatically enabled for Google Drive and Dropbox links.

curl -X POST https://postifys.com/api/facebook/post \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "text": "New image from Postifys API",
    "type": "IMAGE",
    "mediaUrls": ["https://example.com/image.jpg"],
    "pageId": "FACEBOOK_PAGE_ID"
  }'

const response = await fetch("/api/facebook/post", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({
    text: "New Reel from Postifys API",
    type: "REEL",
    mediaUrls: ["https://example.com/reel.mp4"],
    pageId: "FACEBOOK_PAGE_ID"
  })
});
const result = await response.json();

{
  "success": true,
  "historyId": "post_abc123",
  "data": {
    "id": "PAGE_ID_POST_ID"
  }
}

Publish image or Reel to Instagram

Creates a media container and publishes it to a connected Instagram professional account for the API key owner. Pass instagramAccountId for a specific account, or omit it to use the default configured account.

• type string, optional. Use IMAGE, VIDEO, or REEL. Default is IMAGE.
• mediaUrls array or string URL, required.
• url string, optional fallback for mediaUrls.
• text or caption string, optional.
• instagramAccountId string, optional connected Instagram account ID.
• proxyDownload boolean, optional. When true, Postifys downloads the media to a temporary file first. Images are published through a short-lived Postifys URL. Videos and Reels are uploaded to Meta using the resumable upload flow. Temp files are deleted after publish. Automatically enabled for Google Drive and Dropbox links.

curl -X POST https://postifys.com/api/instagram/post \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "IMAGE",
    "mediaUrls": ["https://example.com/post-image.jpg"],
    "text": "Published by Postifys",
    "instagramAccountId": "INSTAGRAM_ACCOUNT_ID"
  }'

curl -X POST https://postifys.com/api/instagram/post \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "REEL",
    "mediaUrls": ["https://drive.google.com/uc?export=download&id=FILE_ID"],
    "text": "New Reel from Google Drive",
    "instagramAccountId": "INSTAGRAM_ACCOUNT_ID",
    "proxyDownload": true
  }'

{
  "success": true,
  "historyId": "post_abc123",
  "data": {
    "id": "INSTAGRAM_MEDIA_ID"
  }
}

Upload a video to YouTube

Uploads a video URL to the connected YouTube channel for the API key owner. Postifys downloads the file to temporary storage, uploads it to YouTube, records history, then deletes the temp file.

• title string, required.
• description string, optional.
• channelId string, optional. Must match one of the connected YouTube channels for the API key owner.
• videoUrl string, required. Must be a downloadable video URL.
• thumbnailUrl string, optional. Public image URL for a custom YouTube thumbnail. If omitted, YouTube uses an auto-generated thumbnail frame.
• privacyStatus string, optional. Use private, unlisted, or public. Default is private.
• tags array or comma-separated string, optional.
• categoryId string, optional. Default is 22.
• notifySubscribers boolean, optional. Default is false.

curl -X POST https://postifys.com/api/youtube/post \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "title": "New video from Postifys",
    "description": "Uploaded through the Postifys API",
    "channelId": "YOUTUBE_CHANNEL_ID",
    "videoUrl": "https://example.com/video.mp4",
    "thumbnailUrl": "https://example.com/thumbnail.jpg",
    "privacyStatus": "private",
    "tags": ["postifys", "automation"],
    "categoryId": "22",
    "notifySubscribers": false
  }'

{
  "success": true,
  "historyId": "post_abc123",
  "data": {
    "id": "YOUTUBE_VIDEO_ID",
    "url": "https://www.youtube.com/watch?v=YOUTUBE_VIDEO_ID"
  }
}

Google may restrict uploads from new or unaudited API projects to private visibility until the project passes YouTube API verification.

Publish an image pin to Pinterest

Creates an image pin on a connected Pinterest board for the API key owner. Postifys can proxy-download the image first when the source URL is not directly fetchable by Pinterest.

• boardId string, required. Pinterest board ID from GET /api/pinterest/boards.
• title string, required.
• description string, optional.
• link string URL, optional destination URL for the pin.
• imageUrl string, required. Public image URL. You can also pass the first item in mediaUrls.
• pinterestUserId string, optional. Required only when multiple Pinterest accounts are connected.
• proxyDownload boolean, optional. When true, Postifys downloads the image to a temporary file first and exposes a short-lived Postifys URL for Pinterest to fetch. Automatically enabled for Google Drive and Dropbox links.

curl -X POST https://postifys.com/api/pinterest/post \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "boardId": "PINTEREST_BOARD_ID",
    "title": "New pin from Postifys",
    "description": "Published through the Postifys API",
    "link": "https://example.com",
    "imageUrl": "https://example.com/pin-image.jpg"
  }'

{
  "success": true,
  "historyId": "post_abc123",
  "data": {
    "id": "PINTEREST_PIN_ID"
  }
}

Pinterest Trial access allows read endpoints only. Apply for Standard access before production pin creation.

Publish a member post to LinkedIn

Publishes a text, image, video, or link-preview post to a connected LinkedIn member account for the API key owner.

• text string, required.
• linkedinUserId string, optional. Required only when multiple LinkedIn accounts are connected.
• postType string, optional. Use text, image, video, or link. Auto-detected from media fields when omitted.
• imageUrl string URL, required for image posts. Public image URL to upload and attach as native LinkedIn media.
• videoUrl string URL, required for video posts. Public video URL to upload and attach as native LinkedIn media.
• link string URL, required for link-preview posts.
• title string, optional title for the image or link preview.

curl -X POST https://postifys.com/api/linkedin/post \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "linkedinUserId": "LINKEDIN_MEMBER_ID",
    "postType": "image",
    "text": "Published through Postifys",
    "imageUrl": "https://example.com/image.jpg",
    "title": "Postifys by Foldious"
  }'

{
  "success": true,
  "historyId": "post_abc123",
  "data": {
    "id": "urn:li:share:1234567890",
    "status": 201
  }
}

Company Page publishing is deferred until LinkedIn grants Community Management access.

Publish a video to TikTok

Publishes a video by URL using TikTok's PULL_FROM_URL flow. The server queries creator info, initializes the publish, then polls until completion.

• tiktokAccountId string, optional when only one TikTok account is connected. Use the id from /api/connections.
• videoUrl string, required. Public MP4 URL recommended.
• caption string, optional. TikTok title/caption.
• privacy string, optional. Default is PUBLIC_TO_EVERYONE.
• disableComment, disableDuet, disableStitch booleans, optional.

curl -X POST https://postifys.com/api/tiktok/post \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "tiktokAccountId": "OPEN_ID_FROM_CONNECTIONS",
    "videoUrl": "https://example.com/video.mp4",
    "caption": "Published with Postifys #socialmedia",
    "privacy": "PUBLIC_TO_EVERYONE",
    "disableComment": false,
    "disableDuet": false,
    "disableStitch": false
  }'

{
  "success": true,
  "data": {
    "publish_id": "v_pub_url...",
    "status": "PUBLISH_COMPLETE",
    "creator_nickname": "Creator Name",
    "creator_username": "creatorhandle"
  }
}

Refresh TikTok access token

Refreshes the TikTok token using TIKTOK_CLIENT_KEY, TIKTOK_CLIENT_SECRET, and TIKTOK_REFRESH_TOKEN.

curl -X POST https://postifys.com/api/tiktok/refresh-token \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{}'

{
  "success": true,
  "message": "Token refreshed. Update TIKTOK_ACCESS_TOKEN and TIKTOK_REFRESH_TOKEN in your .env file.",
  "data": {
    "access_token": "new_access_token",
    "refresh_token": "new_refresh_token",
    "expires_in": 86400
  }
}

Read publish history

Use status as failed, published, pending, or all.

curl "https://postifys.com/api/posts/history?status=failed" \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

{
  "posts": [
    {
      "id": "post_abc123",
      "platform": "instagram",
      "status": "failed",
      "targetName": "brand_account",
      "text": "Caption text",
      "mediaUrls": ["https://example.com/image.jpg"],
      "failureReason": "Media URL could not be fetched",
      "createdAt": 1751540400000
    }
  ]
}

Read one history item

curl https://postifys.com/api/posts/history/post_abc123 \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

Retry a failed post

Retries a failed Facebook or Instagram publish attempt with the same text, media URLs, platform, and target account.

curl -X POST https://postifys.com/api/posts/post_abc123/retry \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

{
  "success": true,
  "historyId": "post_retry123",
  "data": {
    "id": "PAGE_POST_ID"
  }
}

Read Meta OAuth configuration

Returns whether the Meta app ID is configured, the login URL, redirect URI, and live OAuth scopes.

curl https://postifys.com/api/meta/config

{
  "configured": true,
  "loginUrl": "/auth/meta/start",
  "redirectUri": "https://postifys.com/auth/meta/callback",
  "scopes": [
    "public_profile",
    "business_management",
    "pages_show_list",
    "pages_read_engagement",
    "pages_manage_posts",
    "instagram_basic",
    "instagram_content_publish"
  ]
}

Settings and API key page

Users create, view, copy, delete, and recreate their single API key from this web page.

Check Meta credential status

Verifies the configured Meta app ID and app secret by requesting an app access token.

curl https://postifys.com/api/meta/status

Build Meta OAuth URL

Returns the Facebook OAuth dialog URL for the logged-in Postifys user. Redirects to login if there is no session.

curl -i https://postifys.com/api/meta/auth-url \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

Read connected accounts

Returns Meta Pages and Instagram accounts stored for the logged-in user, plus token health. When reconnectRequired is true, the user should reconnect Facebook from the dashboard.

curl https://postifys.com/api/meta/connected-accounts \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

{
  "accounts": [
    { "id": "123", "name": "My Page", "platform": "facebook" },
    { "id": "456", "name": "my_ig", "platform": "instagram" }
  ],
  "connected": true,
  "tokenStatus": "valid",
  "reconnectRequired": false,
  "expiresAt": 1750000000,
  "updatedAt": 1749000000000
}

Read Meta connection details

Server-backed connection summary for the dashboard, including stored page and Instagram account lists and token expiry status.

curl https://postifys.com/api/meta/connection \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

Disconnect Meta

Removes stored Meta tokens and connected account data for the logged-in user.

curl -X DELETE https://postifys.com/api/meta/connection \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

{ "success": true, "disconnected": true }

Start Facebook Login

Creates an OAuth state cookie and redirects the browser to Facebook Login.

https://postifys.com/auth/meta/start

Handle Meta OAuth callback

Meta redirects here with code and state. The server validates the state, exchanges the code, fetches Pages and Instagram accounts, then returns the user to the dashboard.

https://postifys.com/auth/meta/callback?code=CODE_FROM_META&state=STATE

Read YouTube OAuth configuration

curl https://postifys.com/api/youtube/config

Start YouTube OAuth

Redirects the logged-in user to Google OAuth with YouTube upload permissions.

https://postifys.com/auth/youtube/start

Handle YouTube OAuth callback

Validates OAuth state, exchanges the authorization code, stores access and refresh tokens, fetches the channel, then returns the user to the dashboard.

Read YouTube connection

curl https://postifys.com/api/youtube/connection \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

Disconnect YouTube

Removes stored YouTube channel tokens for the logged-in user. Pass channelId to remove one channel, or omit it to remove all YouTube channels.

curl -X DELETE https://postifys.com/api/youtube/connection \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

Read Pinterest OAuth configuration

curl https://postifys.com/api/pinterest/config

{
  "configured": true,
  "loginUrl": "/auth/pinterest/start",
  "redirectUri": "https://postifys.com/auth/pinterest/callback",
  "scopes": ["user_accounts:read", "boards:read", "boards:write", "pins:read", "pins:write"],
  "apiBaseUrl": "https://api.pinterest.com",
  "accessNote": "Pinterest Trial access allows read endpoints only. Apply for Standard access before production pin creation."
}

Start Pinterest OAuth

Redirects the logged-in user to Pinterest OAuth with board read and pin write permissions.

https://postifys.com/auth/pinterest/start

Handle Pinterest OAuth callback

Validates OAuth state, exchanges the authorization code, stores access and refresh tokens, fetches the Pinterest account profile, then returns the user to the dashboard.

https://postifys.com/auth/pinterest/callback?code=CODE_FROM_PINTEREST&state=STATE

Read Pinterest connection

curl https://postifys.com/api/pinterest/connection \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

Read connected Pinterest boards

Returns boards for the authenticated user's connected Pinterest account. n8n uses this endpoint to populate the Pinterest Board dropdown.

curl https://postifys.com/api/pinterest/boards \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "boards": [
    {
      "id": "1234567890",
      "name": "Marketing Ideas"
    }
  ]
}

Disconnect Pinterest

Removes stored Pinterest tokens for the logged-in user. Pass pinterestUserId to remove one account, or omit it to remove all Pinterest accounts.

curl -X DELETE "https://postifys.com/api/pinterest/connection?pinterestUserId=PINTEREST_USER_ID" \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

Read LinkedIn OAuth configuration

curl https://postifys.com/api/linkedin/config

{
  "configured": true,
  "loginUrl": "/auth/linkedin/start",
  "redirectUri": "https://postifys.com/auth/linkedin/callback",
  "scopes": ["openid", "profile", "email", "w_member_social"],
  "apiBaseUrl": "https://api.linkedin.com"
}

Start LinkedIn OAuth

Redirects the logged-in user to LinkedIn OAuth with OpenID profile access and member sharing permission.

https://postifys.com/auth/linkedin/start

Handle LinkedIn OAuth callback

Validates OAuth state, exchanges the authorization code, stores the member access token, fetches the OpenID profile, then returns the user to the dashboard.

https://postifys.com/auth/linkedin/callback?code=CODE_FROM_LINKEDIN&state=STATE

Read LinkedIn connection

curl https://postifys.com/api/linkedin/connection \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

Disconnect LinkedIn

Removes stored LinkedIn tokens for the logged-in user. Pass linkedinUserId to remove one account, or omit it to remove all LinkedIn accounts.

curl -X DELETE "https://postifys.com/api/linkedin/connection?linkedinUserId=LINKEDIN_MEMBER_ID" \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

Get current user

Returns the logged-in Postifys user from the session cookie.

curl https://postifys.com/api/me \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

{
  "user": {
    "id": "user_id",
    "name": "User Name",
    "email": "user@example.com"
  }
}

Create Postifys account

Creates a user and sends/logs a 6-digit verification code.

curl -i -X POST https://postifys.com/signup \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "name=Test User&email=test@example.com&password=secret123"

Verify email

Validates the OTP code and creates a logged-in session.

curl -i -X POST https://postifys.com/verify-email \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "email=test@example.com&code=123456"

Resend email verification code

curl -i -X POST https://postifys.com/verify-email/resend \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "email=test@example.com"

Login

Creates a postifys_session HttpOnly cookie on success.

curl -i -X POST https://postifys.com/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "email=test@example.com&password=secret123&next=/app"

Start Google sign-in

Redirects to Google with openid email profile scopes, then returns through /auth/google/callback to create or log in a Postifys user.

https://postifys.com/auth/google/start?next=/app

Request password reset

curl -i -X POST https://postifys.com/forgot-password \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "email=test@example.com"

Reset password

curl -i -X POST https://postifys.com/reset-password \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "email=test@example.com&code=123456&password=newsecret123"

Logout

Destroys the current session cookie and redirects to the homepage.

curl -i -X POST https://postifys.com/logout \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"

curl https://postifys.com/api/connections \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "connections": [
    {
      "id": "page_123",
      "platform": "facebook",
      "name": "My Facebook Page",
      "username": null,
      "avatar_url": "https://example.com/avatar1.jpg",
      "status": "connected"
    },
    {
      "id": "ig_456",
      "platform": "instagram",
      "name": "My Instagram Account",
      "username": "@my_ig",
      "avatar_url": "https://example.com/avatar2.jpg",
      "status": "connected"
    }
  ]
}

Verify Meta webhook

Returns the challenge when hub.mode=subscribe and hub.verify_token matches META_WEBHOOK_VERIFY_TOKEN.

curl "https://postifys.com/webhooks/meta?hub.mode=subscribe&hub.verify_token=TOKEN&hub.challenge=abc123"

Receive Meta webhook events

Logs the event payload and returns HTTP 200.

curl -X POST https://postifys.com/webhooks/meta \
  -H "Content-Type: application/json" \
  -d '{"object":"page","entry":[]}'

Handle Meta data deletion callback

Verifies Meta's signed request, deletes the user's stored Facebook and Instagram connection data, and returns a status URL with a confirmation code.

curl -X POST https://postifys.com/webhooks/meta/data-deletion \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "signed_request=SIGNED_REQUEST_FROM_META"

{
  "url": "https://postifys.com/data-deletion/del_...",
  "confirmation_code": "del_..."
}

Health check

curl https://postifys.com/health

{
  "status": "ok",
  "message": "Postifys API is running"
}

Marketing homepage

Dashboard

This documentation page

n8n community node feature and setup page

Account pages

Browser pages for account creation, login, email verification, and password recovery.

Legal pages

TikTok site verification file

The same verification signature is also served below /legal/terms.html/....

{
  "success": false,
  "error": {
    "message": "Platform error details"
  }
}