Docs/API Reference

API Reference

The Crosspostify API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

You like Swagger documentation better?

Check out our Swagger API documentation.

Not a developer?

Use Crosspostify's dashboard to get started with social media posting.

Base URL

https://v1.api.crosspostify.com

Authentication

All API requests require authentication using an API key. Include your API key in the X-API-Key header with every request.
The API key can be retrieved in the Crosspostify App.

Keep your API key secure

Your API key carries many privileges, so be sure to keep it secure! Do not share your secret API key in publicly accessible areas such as GitHub, client-side code, and so forth.

Rate Limits

To ensure fair usage and maintain service quality, the Crosspostify API implements rate limiting:

Global Rate Limit
250 requests per hour
Burst Rate Limit
50 requests per minute
Post Creation
3 requests per minute per social account

When you exceed a rate limit, you'll receive a 429 status code. We recommend implementing exponential backoff in your applications.

Errors

Crosspostify uses conventional HTTP response codes to indicate the success or failure of an API request.

200
OK

Everything worked as expected.

400
Bad Request

The request was unacceptable, often due to missing a required parameter.

401
Unauthorized

No valid API key provided.

404
Not Found

The requested resource doesn't exist.

429
Too Many Requests

Too many requests hit the API too quickly.

500
Server Error

Something went wrong on Crosspostify's end.

Endpoints

Below are all the available API endpoints organized by functionality.

POST/post/image

Create a new single image post across multiple social media platforms.

Platform Support & Notes

  • Only supported for TikTok, Instagram, Facebook, LinkedIn, Pinterest, Tumblr, Bluesky
  • title only used for TikTok and Pinterest
  • boardId is mandatory for every Pinterest Account
  • All datetime values must be in UTC timezone (ISO 8601 format with 'Z' suffix)

Request Body

mediaIdstringrequired

The ID of the uploaded image media file

postsarrayrequired

Array of post objects containing account and content information

posts[].accountIdstringrequired

The ID of the social media account to post to

posts[].captionstringrequired

The caption/text content for the post

posts[].titlestringoptional

Post title (only used for TikTok and Pinterest)

posts[].boardIdstringoptional

Pinterest board ID (mandatory for Pinterest accounts)

posts[].scheduledDatestringoptional

Schedule the post for a specific time (ISO 8601 format with 'Z' suffix)

posts[].facebookFirstCommentstringoptional

First comment for Facebook posts (ignored for non-Facebook platforms).

Response

{ "success": true, "data": { "postId": "post_abc123", "status": "SCHEDULED", "scheduledDate": "2024-01-15T10:00:00Z", "accounts": [ { "accountId": "acc_789", "platform": "instagram", "status": "SCHEDULED" } ] } }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/image" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "img_12345",
    "posts": [
      {
        "accountId": "acc_789",
        "caption": "Check out our new product!",
        "title": "New Product Announcement",
        "boardId": "board_123",
        "scheduledDate": "2025-01-15T10:00:00Z",  
        "facebookFirstComment": "This is my first comment on Facebook"
      }
    ]
  }'
POST/post/images

Create a new multiple images post across multiple social media platforms.

Platform Image Limits

  • Instagram: Maximum 10 images per post
  • TikTok: Maximum 10 images per post
  • LinkedIn: Maximum 10 images per post
  • Pinterest: Maximum 5 images per post
  • Tumblr: Maximum 10 images per post
  • Bluesky: Maximum 4 images per post

Notes

  • Only supported for TikTok, Instagram, LinkedIn, Pinterest, Tumblr and Bluesky
  • title only used for TikTok and Pinterest
  • boardId is mandatory for every Pinterest Account
  • For Pinterest all images in a multiple image post must have the same aspect ratio
  • All datetime values must be in UTC timezone (ISO 8601 format with 'Z' suffix)

Request Body

mediaIdsarrayrequired

Array of uploaded image media file IDs (max varies by platform)

postsarrayrequired

Array of post objects containing account and content information

posts[].accountIdstringrequired

The ID of the social media account to post to

posts[].captionstringrequired

The caption/text content for the post

posts[].titlestringoptional

Post title (only used for TikTok and Pinterest)

posts[].boardIdstringoptional

Pinterest board ID (mandatory for Pinterest accounts)

posts[].scheduledDatestringoptional

Schedule the post for a specific time (ISO 8601 format with 'Z' suffix)

posts[].facebookFirstCommentstringoptional

First comment for Facebook posts (ignored for non-Facebook platforms).

Response

{ "success": true, "data": { "postId": "post_def456", "status": "SCHEDULED", "scheduledDate": "2024-01-15T10:00:00Z", "mediaCount": 2, "accounts": [ { "accountId": "acc_789", "platform": "instagram", "status": "SCHEDULED" } ] } }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/images" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaIds": ["img_12345", "img_67890"],
    "posts": [
      {
        "accountId": "acc_789",
        "caption": "Check out our new products!",
        "title": "New Product Collection",
        "boardId": "board_123",
        "scheduledDate": "2025-01-15T10:00:00Z",  
        "facebookFirstComment": "Drop your thoughts below 👇"
      }
    ]
  }'
POST/post/video

Create a new video post across multiple social media platforms.

Notes

  • title only used for YouTube and Pinterest
  • link only used for Pinterest
  • boardId is mandatory for every Pinterest Account
  • All datetime values must be in UTC timezone (ISO 8601 format with 'Z' suffix)

Request Body

mediaIdstringrequired

The ID of the uploaded video media file

postsarrayrequired

Array of post objects containing account and content information

posts[].accountIdstringrequired

The ID of the social media account to post to

posts[].captionstringrequired

The caption/text content for the post

posts[].titlestringoptional

Post title (only used for YouTube and Pinterest)

posts[].linkstringoptional

Link URL (only used for Pinterest)

posts[].boardIdstringoptional

Pinterest board ID (mandatory for Pinterest accounts)

posts[].scheduledDatestringoptional

Schedule the post for a specific time (ISO 8601 format with 'Z' suffix)

posts[].facebookFirstCommentstringoptional

First comment for Facebook posts (ignored for non-Facebook platforms).

Response

{ "success": true, "data": { "postId": "post_ghi789", "status": "PROCESSING", "scheduledDate": "2024-01-15T10:00:00Z", "videoDuration": 45, "accounts": [ { "accountId": "acc_789", "platform": "tiktok", "status": "PROCESSING" } ] } }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/video" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "vid_12345",
    "posts": [
      {
        "accountId": "acc_789",
        "caption": "Watch our latest video!",
        "title": "New Video Release",
        "link": "https://example.com",
        "boardId": "board_123",
        "scheduledDate": "2025-01-15T10:00:00Z",  
        "facebookFirstComment": "First comment with extra info and links"
      }
    ]
  }'
POST/post/text

Create a text-only post. Currently supported for Facebook Pages only.

Platform Support & Notes

  • Supported platforms: Facebook
  • No media is required or accepted for this endpoint
  • All datetime values must be in UTC timezone (ISO 8601 format with 'Z' suffix)

Request Body

postsarrayrequired

Array of post objects containing account and text content

posts[].accountIdstringrequired

The ID of the Facebook Page social account to post to

posts[].captionstringrequired

The text content for the post

scheduledDatestringoptional

Schedule the post for a specific time (ISO 8601 format with 'Z' suffix). If omitted, the post is queued immediately.

posts[].textFormatPresetIdstring | integeroptional

Facebook text background preset ID. Applies only to Facebook text posts. Must be numeric.

posts[].facebookFirstCommentstringoptional

First comment for Facebook posts (ignored for non-Facebook platforms).

Validation

  • If provided, textFormatPresetId must be numeric (string or integer). Otherwise the request is rejected with HTTP 400.
  • Ignored for non-Facebook platforms.

Response

{ "message": "Text-only post created successfully", "posts": [ { "id": "post_abc123", "socialAccountId": "acc_facebook_page_123", "platform": "facebook", "status": "QUEUED" } ] }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/text" \  
  -H "X-API-Key: your_api_key_here" \  
  -H "Content-Type: application/json" \  
  -d '{  
    "scheduledDate": "2025-01-15T10:00:00Z",  
    "posts": [  
      {  
        "accountId": "acc_facebook_page_123",  
        "caption": "Hello Facebook! This is a text-only post with a background.",  
        "textFormatPresetId": "106018623298955",
        "facebookFirstComment": "P.S. Don’t miss our live Q&A at 5 PM!"
      }  
    ]  
  }'

Facebook Text Background Presets

You can optionally provide textFormatPresetId for Facebook text-only posts. The value is forwarded to Facebook as text_format_preset_id. Keep IDs as strings in requests to avoid numeric precision issues.

IDLabel
106018623298955Solid purple
365653833956649Pink tropical plants
618093735238824Brown illustration
1917619914913753D hearts
21936277939854153D heart eyes emojis
2005213374653063D flame emojis
1821844087883360Walking yellow illustration
177465482945164Light purple 3D cube pattern
160419724814650Orange with pink illustration
2486239024012503D smiling emoji
2404018167717063D rose emojis
18688559434173603D crying laughter emoji
255989551804163Eye pink illustration
1654916007940525Light grey illustration
1679248482160767Light blue illustration
518948401838663Pink heart pattern
423339708139719Illustration
204187940028597Solid red
621731364695726Solid red
518596398537417Red illustration
134273813910336Tree red illustration
217321755510854Pink/purple hearts on pink
323371698179784Sunset red illustration
901751159967576Gradient dark orange/red
552118025129095Brown illustration
263789377694911Apple red illustration
606643333067842Tulip light orange illustration
458988134561491Cat dark orange illustration
548109108916650Unicorn red illustration
175493843120364Pink/yellow gradient
338976169966519Stairs beige illustration
206513879997925Spiral beige illustration
168373304017982Cube beige illustration
1271157196337260Solid red
174496469882866Lemon yellow illustration
862667370603267Egg light yellow illustration
127541261450947Ball green illustration
218067308976029Light grey illustration
688479024672716Gradient teal/light green
238863426886624Cat light blue illustration
301029513638534Solid teal
154977255088164Solid teal
1941912679424590Gradient grey/dark grey
396343990807392Flower teal illustration
143093446467972Blue clouds on dark blue
161409924510923Rocket heart in the sky
145893972683590Solid dark purple
217761075370932Solid blue
931584293685988Wave blue illustration
148862695775447Pink/purple hearts on purple
100114277230063Deep sea blue illustration
558836317844129Spiral purple illustration
172497526576609Watermelon light purple
433967226963128Solid purple
197865920864520Donut light purple
643122496026756Pink illustration
762009070855346Balloon light grey illustration
228164237768720Grey hearts on black
146487026137131Rain black illustration
221828835275596Glasses light grey illustration
1903718606535395Solid red
1881421442117417Solid black
249307305544279Gradient red/blue
1777259169190672Gradient purple/magenta
303063890126415Yellow/orange/pink gradient
122708641613922Gradient dark grey/black
319468561816672Dark blue illustration
121945541697934Pink illustration
288211338285858Blue illustration
446330032368780Gradient red
219266485227663Solid magenta
1289741387813798Solid dark red
1365883126823705Solid blue

Notes

  • This list can change over time per Facebook.
  • Unknown or invalid IDs will receive a 400 validation error.
  • Leave textFormatPresetId empty to post with no background.
GET/pinterest-boards/accountId

Get Pinterest boards for a specific account.

Path Parameters

accountIdstringrequired

The ID of the Pinterest account

Response

{ "success": true, "data": { "boards": [ { "id": "board_123", "name": "My Recipes", "description": "Delicious recipes to try", "pinCount": 45, "privacy": "PUBLIC" }, { "id": "board_456", "name": "Travel Ideas", "description": "Places I want to visit", "pinCount": 23, "privacy": "SECRET" } ] } }

Code Example

curl -X GET "https://v1.api.crosspostify.com/pinterest-boards/acc_123" \
  -H "X-API-Key: your_api_key_here"
GET/social-accounts

Get user's connected social media accounts.

Query Parameters

platformstringoptional

Filter by platform (facebook, instagram, tiktok, pinterest, etc.)

Response

{ "success": true, "data": { "accounts": [ { "id": "acc_123", "platform": "instagram", "username": "@myaccount", "displayName": "My Account", "isActive": true, "connectedAt": "2024-01-01T00:00:00Z" }, { "id": "acc_456", "platform": "facebook", "username": "My Page", "displayName": "My Facebook Page", "isActive": true, "connectedAt": "2024-01-02T00:00:00Z" } ] } }

Code Example

curl -X GET "https://v1.api.crosspostify.com/social-accounts" \
  -H "X-API-Key: your_api_key_here"
GET/posts

Get user posts with filtering and pagination options.

Query Parameters

statusstringoptional

Filter by post status (QUEUED, SCHEDULED, PUBLISHED, FAILED)

platformstringoptional

Filter by platform (facebook, instagram, tiktok, etc.)

limitintegeroptional

Number of posts to return (max 100, default 50)

Response

{ "success": true, "data": { "posts": [ { "id": "post_123", "status": "PUBLISHED", "caption": "Check out our new product!", "mediaType": "IMAGE", "platform": "instagram", "publishedAt": "2024-01-15T10:00:00Z", "engagement": { "likes": 45, "comments": 12, "shares": 3 } } ], "pagination": { "total": 150, "page": 1, "limit": 50, "hasMore": true } } }

Code Example

curl -X GET "https://v1.api.crosspostify.com/posts?limit=10" \
  -H "X-API-Key: your_api_key_here"
DELETE/posts/postId

Delete a scheduled post (only works for posts that haven't been published yet).

Path Parameters

postIdstringrequired

The ID of the post to delete

Response

{ "success": true, "data": { "message": "Post deleted successfully", "postId": "post_123", "deletedAt": "2024-01-15T09:30:00Z" } }

Code Example

curl -X DELETE "https://v1.api.crosspostify.com/posts/post_123" \
  -H "X-API-Key: your_api_key_here"
GET/media

Get user's uploaded media files.

Query Parameters

typestringoptional

Filter by media type (IMAGE, VIDEO)

limitintegeroptional

Number of media files to return (max 100, default 50)

Response

{ "success": true, "data": { "media": [ { "id": "img_123", "type": "IMAGE", "filename": "product-photo.jpg", "url": "https://cdn.crosspostify.com/img_123.jpg", "size": 2048576, "dimensions": { "width": 1920, "height": 1080 }, "uploadedAt": "2024-01-15T08:00:00Z" } ], "pagination": { "total": 25, "page": 1, "limit": 50, "hasMore": false } } }

Code Example

curl -X GET "https://v1.api.crosspostify.com/media" \
  -H "X-API-Key: your_api_key_here"
POST/media

Upload a media file (image or video) for later use in posts.

Request Body (multipart/form-data)

mediafilerequired

The media file to upload (max 100MB for images, 500MB for videos)

typestringrequired

Media type: IMAGE or VIDEO

Response

{ "success": true, "data": { "id": "img_456", "type": "IMAGE", "filename": "new-product.jpg", "url": "https://cdn.crosspostify.com/img_456.jpg", "size": 1536000, "dimensions": { "width": 1200, "height": 800 }, "uploadedAt": "2024-01-15T09:00:00Z" } }

Code Example

curl -X POST "https://v1.api.crosspostify.com/media" \
  -H "X-API-Key: your_api_key_here" \
  -F "[email protected]" \
  -F "type=IMAGE"
DELETE/media/mediaId

Delete a media file from your account.

Path Parameters

mediaIdstringrequired

The ID of the media file to delete

Response

{ "success": true, "data": { "message": "Media file deleted successfully", "mediaId": "img_123", "deletedAt": "2024-01-15T09:45:00Z" } }

Code Example

curl -X DELETE "https://v1.api.crosspostify.com/media/img_123" \
  -H "X-API-Key: your_api_key_here"