Postifys Developer Hub
Developer API

Postifys API Reference

Use these endpoints to check service health, manage Postifys user sessions, connect Meta and YouTube accounts, publish to social platforms, and track publish history.

Production Base URL https://postifys.com
Guides: Docs home · Getting started · Authentication · Create a post · Media · Errors · Webhooks · Rate limits
Search API
Navigation
Search API
Start here

Quick Start

Publishing endpoints use the connected Facebook Pages, Instagram professional accounts, and YouTube channel for the API key owner. Pass a specific pageId or instagramAccountId to target one Meta account.

Authentication

Publishing endpoints require either a logged-in Postifys browser session or an API key created from /settings. Send API keys as Authorization: Bearer YOUR_API_KEY or X-API-Key: YOUR_API_KEY.

Facebook specific Page setup FACEBOOK_PAGE_ID
META_ACCESS_TOKEN
Instagram specific account setup INSTAGRAM_ACCOUNT_ID
META_ACCESS_TOKEN 
curl https://postifys.com/health
API access

Authentication

Postifys users can create multiple masked API keys from the Settings page. Keys can be named, scoped, tracked by last use, deleted, and recreated after deletion. Raw keys are only shown at creation time.

Create or manage keys https://postifys.com/settings
Use this header Authorization: Bearer YOUR_API_KEY 
curl -X POST https://postifys.com/api/facebook/post \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"message":"Hello from Postifys API"}'
curl -X POST https://postifys.com/api/facebook/post \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"message":"Hello from Postifys API"}'
curl https://postifys.com/api/key/test \
  -H "Authorization: Bearer YOUR_API_KEY"
Safe retries

Idempotency-Key header

Publishing endpoints accept an optional Idempotency-Key header. Use one stable key per intended destination post so timeouts, retries, and n8n re-runs do not create duplicate posts.

Behavior

When idempotency enforcement is enabled, the same key with the same payload replays the existing post state. The same key with a different payload returns 409 Conflict. When the server is in monitor mode, keys are recorded for diagnostics without blocking requests.

curl -X POST https://postifys.com/api/youtube/post \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: client-job-123" \
  -d '{
    "title": "Launch video",
    "videoUrl": "https://example.com/video.mp4",
    "channelId": "YOUTUBE_CHANNEL_ID"
  }'
{
  "success": true,
  "idempotent": true,
  "accepted": false,
  "status": "published",
  "postId": "post_abc123",
  "postSubmissionId": "post_abc123",
  "historyId": "post_abc123"
}
Core API

Publishing APIs

Use these endpoints to publish content. Facebook and Instagram publish through Meta Graph API v20.0, YouTube uploads through YouTube Data API v3, Pinterest creates image pins through Pinterest API v5, and TikTok publishes through TikTok Content Posting API v2.

POST /api/facebook/post
Requires API key or session

Publish image, Reel, feed post, or Story to a Facebook Page

Creates a native photo, Reel, text/link feed post, or Page Story 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.

Requires: pages_manage_posts Requires: pages_read_engagement
  • 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, Reels, and Stories.
  • link string URL, optional fallback for mediaUrls.
  • type string, optional. Use IMAGE for native Page photos, REEL for native Facebook Reels, FEED for text/link posts, or STORIES (alias STORY) for Page Stories. Image vs video Stories is inferred from the media URL. Default is IMAGE when media is present and FEED for text-only posts. Stories require META_STORIES_ENABLED=true on the server.
  • 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.
Stories honesty: Plain image/video only (no stickers, polls, or link stickers via API). Stories expire after about 24 hours. Video Stories have Meta duration/format limits. 
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"
  }
}
POST /api/instagram/post
Requires API key or session

Publish image, Reel, or Story 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.

Requires: instagram_business_basic Requires: instagram_business_content_publish
  • type string, optional. Use IMAGE, VIDEO, REEL, or STORIES (alias STORY). Default is IMAGE. Stories require META_STORIES_ENABLED=true on the server. Image vs video Stories is inferred from the media URL.
  • mediaUrls array or string URL, required.
  • url string, optional fallback for mediaUrls.
  • text or caption string, optional (ignored by Meta for Stories).
  • 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.
Stories honesty: Professional accounts only. Plain image/video — no stickers, polls, link stickers, or music via API. Captions are ignored. Stories expire after about 24 hours.
Google Drive and n8n

Use proxyDownload: true for Google Drive links such as https://drive.google.com/uc?export=download&id=FILE_ID. The file must be shared as Anyone with the link. Direct CDN or S3 MP4 URLs can omit proxy mode for faster publishing.

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"
  }
}
POST /api/youtube/post
Requires API key or session

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.

Requires: youtube.upload Video only
  • 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.

POST /api/pinterest/post
Requires API key or session

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.

Requires: pins:write Image only Production API
  • 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"
  }
}

Postifys uses Pinterest Standard access on https://api.pinterest.com. Boards created during Trial are sandbox-only and are excluded from board pickers. Create new boards on Pinterest if an older board no longer appears.

POST /api/linkedin/post
Requires API key or session

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.

Requires: w_member_social Member profile only
  • 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.

POST /api/tiktok/post
Requires API key or session

Publish a video to TikTok

Downloads the video securely, queries the connected creator's current publishing options, uploads the file to TikTok, and polls for status. Direct Post requires the user's explicit confirmation.

Requires: connected TikTok account Video only
  • 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.
  • consent boolean, required as true for Direct Post after showing the creator, caption, privacy, and interaction settings to the user.
  • postMode string, optional. Use direct for Direct Post or inbox to send a draft to TikTok. The server default is used when omitted.
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,
    "consent": true,
    "postMode": "direct"
  }'
{
  "success": true,
  "data": {
    "publish_id": "v_pub_url...",
    "status": "PUBLISH_COMPLETE",
    "creator_nickname": "Creator Name",
    "creator_username": "creatorhandle"
  }
}
POST /api/tiktok/refresh-token
Maintenance

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
  }
}
Publish tracking

Post History APIs

Postifys keeps 15 days of Facebook and Instagram publish attempts for each user, including failure reasons and retry support.

GET /api/posts/history
Requires Postifys login

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
    }
  ]
}
GET /api/posts/history/:id
Requires Postifys login

Read one history item

curl https://postifys.com/api/posts/history/post_abc123 \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"
POST /api/posts/:id/retry
Requires Postifys login

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

Meta APIs

Use these endpoints to inspect Meta configuration, start Facebook Login for Pages, and verify app credentials. Instagram professional accounts use Instagram Business Login separately.

GET /api/meta/config
Public

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 connect and publish use Instagram Business Login scopes (instagram_business_basic, instagram_business_content_publish) via /auth/instagram/start, not Facebook Login.

GET /settings
Requires Postifys login

Settings and API key page

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

GET /api/meta/status
Public

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
GET /api/meta/auth-url
Requires Postifys login

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"
GET /api/meta/connected-accounts
Requires Postifys login

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
}
GET /api/meta/connection
Requires Postifys login

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"
DELETE /api/meta/connection
Requires Postifys login

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 }
GET /auth/meta/start
Requires Postifys login

Start Facebook Login

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

https://postifys.com/auth/meta/start
GET /auth/meta/callback
Meta redirect URI

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
Connect YouTube

YouTube APIs

Use these endpoints to inspect YouTube OAuth configuration, connect YouTube channels, and disconnect stored YouTube tokens.

GET /api/youtube/config
Public

Read YouTube OAuth configuration

curl https://postifys.com/api/youtube/config
GET /auth/youtube/start
Requires Postifys login

Start YouTube OAuth

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

https://postifys.com/auth/youtube/start
GET /auth/youtube/callback
Google redirect URI

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.

GET /api/youtube/connection
Requires Postifys login

Read YouTube connection

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

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"
Connect Pinterest

Pinterest APIs

Use these endpoints to inspect Pinterest OAuth configuration, connect Pinterest accounts, list boards, and disconnect stored Pinterest tokens.

GET /api/pinterest/config
Public

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": "Postifys uses Pinterest Standard access on the production API. Boards created during Trial are sandbox-only — create new boards on Pinterest after approval."
}
GET /auth/pinterest/start
Requires Postifys login

Start Pinterest OAuth

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

https://postifys.com/auth/pinterest/start
GET /auth/pinterest/callback
Pinterest redirect URI

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
GET /api/pinterest/connection
Requires Postifys login

Read Pinterest connection

curl https://postifys.com/api/pinterest/connection \
  -H "Cookie: postifys_session=YOUR_SESSION_COOKIE"
GET /api/pinterest/boards
Requires API key or session

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"
    }
  ]
}
DELETE /api/pinterest/connection
Requires Postifys login

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"
Connect LinkedIn

LinkedIn APIs

Use these endpoints to inspect LinkedIn OAuth configuration, connect member accounts, list connected accounts, and disconnect stored LinkedIn tokens.

GET /api/linkedin/config
Public

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"
}
GET /auth/linkedin/start
Requires Postifys login

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
GET /auth/linkedin/callback
LinkedIn redirect URI

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
GET /api/linkedin/connection
Requires Postifys login

Read LinkedIn connection

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

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"
User sessions

Account APIs

These routes power the Postifys web login, signup, verification, and password reset flow. Form routes return redirects rather than JSON.

GET /api/me
Requires Postifys login

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"
  }
}
POST /signup
Form redirect

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"
POST /verify-email
Form redirect

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"
POST /verify-email/resend
Form redirect

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"
POST /login
Form redirect

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"
GET /auth/google/start
Browser OAuth

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
POST /forgot-password
Form redirect

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"
POST /reset-password
Form redirect

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"
POST /logout
Form redirect

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"
GET /api/connections
Requires API key or session

Get all connected accounts

Returns a flat, standardized list of all connected social media profiles and channels (Facebook, Instagram, YouTube, Pinterest, LinkedIn, and TikTok) for the authenticated user.

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

Webhook APIs

Meta uses these endpoints for webhook verification, webhook events, and data deletion requests. Postifys can also send server-configured outbound publish event webhooks when enabled by operations.

Outbound webhook scope

Outbound publish webhooks are currently configured at the server/operator level, not through a public customer self-service API. When configured, Postifys sends publish status events such as post.published and post.failed. If a signing secret is configured, the raw JSON body is signed with X-Postifys-Signature-256.

GET /webhooks/meta
Meta verification

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"
POST /webhooks/meta
Meta events

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":[]}'
POST /webhooks/meta/data-deletion
Meta data deletion

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_..."
}
POST Configured outbound URL
Publish events

Receive outbound publish events

When enabled by Postifys operations, publish state changes are sent to the configured URL. Delivery history is not currently retained in the public API.

{
  "event": "post.published",
  "createdAt": "2026-08-24T09:00:00.000Z",
  "post": {
    "id": "post_abc123",
    "userId": "usr_...",
    "platform": "youtube",
    "status": "published",
    "targetId": "YOUTUBE_CHANNEL_ID",
    "type": "VIDEO",
    "retryOf": null,
    "retryCount": 0,
    "failureReason": null,
    "publishedAt": "2026-08-24T09:00:00.000Z",
    "failedAt": null,
    "updatedAt": "2026-08-24T09:00:00.000Z"
  }
}
Asynchronous media preparation

Media Queue APIs

Queue remote media for background download and inspect its processing status before publishing.

POST /api/media/queue
API key or session required

Queue a media download

Accepts a supported remote media source and returns an asynchronous media job with HTTP status 202.

GET /api/media/status?mediaJobId=MEDIA_JOB_ID
API key or session required

Check media job status

Returns the authenticated user's media job state. The mediaJobId query parameter is required.

GET /api/media/queue
Browser session required

List media jobs

Returns the signed-in user's active, completed, and failed media jobs.

Temporary delivery URLs

Temporary Media API

Prepared files are served from signed temporary URLs used by supported social-platform upload flows.

GET /media/tmp/:token/:filename
Signed token required

Retrieve prepared temporary media

The URL is generated by Postifys for a specific prepared file. Tokens expire and cannot be used to browse other files.

Browser routes

Page and Utility Routes

These routes return HTML pages or simple service responses.

GET /health
JSON

Health check

curl https://postifys.com/health
{
  "status": "ok",
  "message": "Postifys API is running"
}
GET /
HTML

Marketing homepage

GET /app
Requires Postifys login

Dashboard

GET /api-docs
HTML

This documentation page

GET /n8n
HTML

n8n community node feature and setup page

GET /login, /signup, /verify-email, /forgot-password, /reset-password
HTML forms

Account pages

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

GET /legal/privacy.html, /legal/terms.html
HTML

Legal pages

GET /legal/privacy.html/tiktokVFdRH4ORzmeAtL4BlgcCua7697ldVh39.txt
TikTok verification

TikTok site verification file

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

Responses

Error Behavior

JSON endpoints generally return success: false on server errors. Form endpoints usually redirect with query-string error codes.

Common publishing errors

FACEBOOK_PAGE_ID is not set, INSTAGRAM_ACCOUNT_ID is not set, META_ACCESS_TOKEN missing or expired, media URL not publicly reachable, or platform permission not approved.

POST Publishing endpoint error example
500 
{
  "success": false,
  "error": {
    "message": "Platform error details"
  }
}

Continue learning