SoMePoster Developer API Reference

What you can do

• Publish a post immediately to one or many platforms at once.
• Schedule posts for a future date/time — one time for all platforms, or a different time per platform.
• Send different text to each platform in a single request.
• Attach images or a video, including TikTok and YouTube options.
• List every connected account and its sub-targets (e.g. Pinterest boards, Facebook pages).

Before you start

2

Copy your API key

Open the Developer API page in your SoMePoster dashboard and copy your API key.

Keep it secret. Your API key grants full posting access to your account.

Authentication

Authenticate every request with your API key. Two header styles are accepted — use either one.

Option A — Bearer token

Authorization: Bearer YOUR_API_KEY

Option B — x-api-key header

x-api-key: YOUR_API_KEY

Requests without a valid key return 401 Unauthorized.

Rate limits

Limits are applied per API key, per minute:

• GET /api/v1/accounts — 20 requests / minute
• POST /api/v1/posts — 30 requests / minute

Exceeding a limit returns 429 Too Many Requests. Back off and retry after the window resets (the next minute).

Endpoint 1 — List your accounts

Returns every connected account with its id, platform, handle, and any sub-targets. You need these account ids (and target ids, where relevant) to create posts — always call this first.

Response fields

Example request

curl -X GET "https://app.someposter.ai/api/v1/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "accounts": [
    {
      "id": "cmq_account_id",
      "platform": "X",
      "username": "someposter",
      "displayName": "SoMePoster",
      "targets": []
    },
    {
      "id": "cmq_pinterest_account_id",
      "platform": "PINTEREST",
      "username": "SoMePoster",
      "displayName": null,
      "targets": [
        { "id": "board_id", "name": "Product Updates", "type": "pinterest_board" }
      ]
    }
  ]
}

Endpoint 2 — Create a post

Publish now or schedule for later. Send JSON for text-only posts, or multipart/form-data when attaching images or a video.

Core fields

* Provide either content or contentByPlatform (text posts must not be empty).

Text post (publish now)

curl -X POST "https://app.someposter.ai/api/v1/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "now",
    "platforms": ["X"],
    "accounts": { "X": ["cmq_x_account_id"] },
    "content": "Publishing from the SoMePoster API."
  }'

Different text per platform

curl -X POST "https://app.someposter.ai/api/v1/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "now",
    "platforms": ["X", "LINKEDIN"],
    "accounts": {
      "X": ["cmq_x_account_id"],
      "LINKEDIN": ["cmq_linkedin_page_account_id"]
    },
    "contentByPlatform": {
      "X": "Short X version",
      "LINKEDIN": "Longer LinkedIn version with more detail."
    }
  }'

Image post

Attach images with multipart/form-data: put the post JSON in a payload field and add each image as a file. This example also shows posting to a specific board via targets.

curl -X POST "https://app.someposter.ai/api/v1/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F 'payload={
    "mode": "now",
    "platforms": ["PINTEREST"],
    "accounts": { "PINTEREST": ["cmq_pinterest_account_id"] },
    "title": "New product pin",
    "content": "Pin description",
    "targets": {
      "cmq_pinterest_account_id": ["target_id_from_list_accounts"]
    }
  }' \
  -F "files=@/local/path/product.png;type=image/png"

Video post (TikTok + YouTube)

Send the video as a videoFile. TikTok requires privacyLevel and consentAccepted; YouTube options are optional.

curl -X POST "https://app.someposter.ai/api/v1/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F 'payload={
    "mode": "now",
    "platforms": ["YOUTUBE", "TIKTOK"],
    "accounts": {
      "YOUTUBE": ["cmq_youtube_account_id"],
      "TIKTOK": ["cmq_tiktok_account_id"]
    },
    "title": "Product update",
    "content": "Video description",
    "tiktokOptions": {
      "privacyLevel": "PUBLIC_TO_EVERYONE",
      "consentAccepted": true,
      "disableComment": false,
      "disableDuet": false,
      "disableStitch": false,
      "brandOrganicToggle": false,
      "brandContentToggle": false,
      "isAigc": false
    },
    "youtubeOptions": {
      "tags": "product, update",
      "recordingDate": "2026-06-20",
      "location": "Copenhagen, Denmark",
      "publicStatsViewable": true
    }
  }' \
  -F "videoFile=@/local/path/video.mp4;type=video/mp4"

Scheduled post

Set mode to schedule and provide scheduledAt. Use an IANA timezone for local times, or send a full ISO timestamp with offset. For per-platform timing, use scheduledAtByPlatform instead.

curl -X POST "https://app.someposter.ai/api/v1/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "schedule",
    "scheduledAt": "2026-06-20T14:30:00",
    "timezone": "Asia/Karachi",
    "platforms": ["X", "LINKEDIN"],
    "accounts": {
      "X": ["cmq_x_account_id"],
      "LINKEDIN": ["cmq_linkedin_page_account_id"]
    },
    "content": "Going out Friday afternoon."
  }'

Successful response

A successful call queues your deliveries and returns the batch id and a per-delivery summary:

{
  "ok": true,
  "batchId": "cmq_batch_id",
  "editedBatchId": null,
  "mode": "NOW",
  "queued": true,
  "deliveriesCount": 1,
  "results": [
    {
      "platform": "System",
      "success": true,
      "message": "Queued 1 deliveries successfully."
    }
  ]
}

Platform reference

Platform ids

Use these ids in platforms and as keys in accounts:

X, LINKEDIN, INSTAGRAM, FACEBOOK, THREADS, PINTEREST, BLUESKY, TIKTOK, YOUTUBE, GMB, WORDPRESS, WORDPRESSCOM, BLOGGER, MAILCHIMP, TELEGRAM, and more.

Video-capable platforms

Video posts are supported on: TikTok, YouTube, Facebook, Instagram, X, LinkedIn, Pinterest, Bluesky, WordPress.com, and WordPress. Don't include a video for platforms that don't support it — create a separate text/image post instead.

Targets (boards & pages)

Some platforms post to a sub-target rather than the account itself — e.g. a Pinterest board. Read the target id from the targets array in List Accounts and pass it under the targets object keyed by account id.

Media rules

• Images: up to 5 MB each, sent as files in a multipart request.
• Video: one video per request, sent as videoFile. The maximum size depends on your plan (for example, up to 1 GB on higher tiers).
• When attaching any file, the post JSON must be sent in the payload form field (not as a JSON body).

Errors and limits

Errors return a JSON body with an error message (and sometimes a code). Common cases:

• 401 Unauthorized — missing or invalid API key.
• 402 X_POST_LIMIT_REACHED — you've used your monthly X posts; buy extra X posts to continue.
• 403 Feature not in your plan — e.g. scheduling, automations, or Mailchimp on a plan that doesn't include it.
• 400 Validation error — missing platforms, empty content, invalid scheduledAt/timezone, or an unsupported video platform.
• 429 Too Many Requests — you hit the per-minute rate limit; retry next minute.

Best practices

• Call List Accounts first and cache the account/target ids — don't hard-code them.
• Always pass a timezone with scheduled local times so posts go out exactly when intended.
• Keep each request to platforms that share the same media type; split text and video into separate calls when needed.
• Respect the rate limits and handle 429 with a simple retry-after-a-minute backoff.
• Treat your API key like a password — store it in an environment variable, never in client-side code.