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

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[].scheduledForstringoptional

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

Response

{ "success": true, "data": { "postId": "post_abc123", "status": "SCHEDULED", "scheduledFor": "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",
        "scheduledFor": "2024-01-15T10:00:00Z"
      }
    ]
  }'

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[].scheduledForstringoptional

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

Response

{ "success": true, "data": { "postId": "post_def456", "status": "SCHEDULED", "scheduledFor": "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",
        "scheduledFor": "2024-01-15T10:00:00Z"
      }
    ]
  }'

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[].scheduledForstringoptional

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

Response

{ "success": true, "data": { "postId": "post_ghi789", "status": "PROCESSING", "scheduledFor": "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",
        "scheduledFor": "2024-01-15T10:00:00Z"
      }
    ]
  }'

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"