Skip to content

Create Post API: Getting Started

The Create Post API is a social media posting API for publishing and scheduling content across multiple platforms through one integration. This guide walks through the complete first-post flow: authenticate, optionally create a profile, connect a social account, retrieve the accountId, then publish now with publishNow or schedule a post with scheduledFor and timezone.

What the unified posting API does

This social media posting API lets one integration publish, schedule, and manage content across Twitter/X, Instagram, YouTube, Facebook, and more, without separate platform SDKs for each destination. The workflow is deliberately linear: authenticate once, connect each social account through OAuth, collect the accountId for each connection, and then send a single create-post request naming one or more platform targets. Keeping the connection step separate from the posting step means a failed or incomplete OAuth flow is caught before any content request is attempted.

Authentication

All requests use the same access key, sent in the x-access-key header. Before running the full flow, call the health/auth check with that header to confirm the key is accepted. Store the key outside source control, such as in an environment variable, and never place it in a URL or in client-side code that end users can read. If the check fails, stop and fix the key or header before creating profiles or requesting OAuth URLs, because every later step depends on the same authentication.

Step 1: Create a Profile (Optional)

A profile is a label that groups one or more connected social accounts, and creating one is optional. Create it before the connect step when your backend needs to know exactly which integration was just created, for example when end users connect their own accounts from your application. Send POST /v1/profiles with a name field, then save the returned profile id. That value becomes profileId in the connect and integrations-listing steps. If you do not need that grouping or filtering, you can skip this step and go straight to connecting an account.

Step 2: Connect a Social Account

To connect a social account, request the OAuth URL for the chosen platform with GET /v1/connect/{platform}. Pass profileId as a query parameter only if you created a profile in the previous step; otherwise omit it. The response contains a url field. Redirect the user to that url and let them authorize. After authorization completes, the account is connected to your project and, when profileId was supplied, bound to that profile. Do not attempt to post until the integrations list confirms the new connection.

Step 3: Get Your Account ID

Posting requires an accountId, which is the id of a connected integration. List integrations with GET /v1/connect/integrations and, when you used a profile, add the profileId query parameter so the response shows only the integration you just created. Each integration entry includes its id, platform, platformUserId, profileId, and createdAt. Copy the id value into the accountId field of the matching platforms entry in your post request. If the list is empty, the OAuth flow did not complete; repeat the connect step rather than guessing an identifier.

Step 4: Publish Your First Post

Publish with POST /v1/posts. The request body needs content, a platforms array, and publishNow set to true for immediate publishing. Each platforms entry names a platform and the accountId for the connected account on that platform, so the same content can target several destinations in one request. A successful response reports success, a status of published, a postId, and per-platform results including platformPostUrl for the published item. Check the per-platform success values as well as the top-level status, because the response distinguishes overall status from each destination result.

Step 5: Schedule a Post (Optional)

To schedule a post instead of publishing immediately, use the same POST /v1/posts endpoint but provide scheduledFor and timezone in place of the immediate-publishing field. scheduledFor is the scheduled date and time, and timezone identifies the zone that time is expressed in, such as America/New_York. Keep the content and platforms fields the same as the immediate example. Before scheduling, double-check the timezone value and the accountId, since both are carried into the scheduled request exactly as written.

Supported Platforms

The supported-platforms table below lists each destination, its Live status, and the features shown for it in the source. Use it to decide which platform value and connected account to target, and to set expectations about what content types each destination supports, such as threads and polls on Twitter/X, Shorts on YouTube, or Reels on Instagram. Platform availability and feature lists should be rechecked against the current reference before building a production flow around a specific destination.

Next Steps

After your first post succeeds, continue with the Authentication reference for API keys, credits, and rate limits, the Connect Accounts reference for OAuth flows per platform, the Publishing reference for the full create-post request and response, and the Scheduling reference for scheduling, cancelling, and rescheduling posts. Those references expand the same steps covered here without changing the field names or endpoint paths used in this guide.

Endpoint contract for the first-post flow
MethodPathHeader / ParameterPurpose
GET/v1/health/authx-access-key headerCheck authentication
POST/v1/profilesx-access-key header; body field nameCreate an optional profile
GET/v1/connect/{platform}x-access-key header; optional profileId query parameterGet OAuth url for a platform
GET/v1/connect/integrationsx-access-key header; optional profileId query parameterList integrations and retrieve accountId
POST/v1/postsx-access-key header; Content-Type: application/jsonPublish now or schedule a post

Exact methods and paths from the captured source; origin shown as {{API_BASE_URL}}.

Create-post request and response field map
FieldLocationRequiredness in shown examplesNotes
contentPOST /v1/posts bodyShown in both examplesPost text
platformsPOST /v1/posts bodyShown in both examplesArray of platform targets
platforms[].platformPOST /v1/posts bodyShown in both examplesExample value: twitter
platforms[].accountIdPOST /v1/posts bodyShown in both examplesIntegration id from GET /v1/connect/integrations
publishNowPOST /v1/posts bodyShown in immediate exampleSet to true to publish now
scheduledForPOST /v1/posts bodyShown in schedule exampleScheduled date and time
timezonePOST /v1/posts bodyShown in schedule exampleExample value: America/New_York
successPOST /v1/posts responseReturnedOverall result flag
statusPOST /v1/posts responseReturnedExample value: published
postIdPOST /v1/posts responseReturnedIdentifier of the created post
platforms[].platformPostUrlPOST /v1/posts responseReturned per platformURL of the published platform post

Fields exactly as shown in the captured publish and schedule examples.

Supported platforms
PlatformStatusFeatures
Twitter/XLivePosts, threads, polls, images, videos, GIFs
YouTubeLiveVideo uploads, Shorts, metadata
LinkedInLivePosts, images, videos
PinterestLivePins with images
BlueskyLiveText posts, images, link cards
TikTokLiveVideos, photos, photo carousels
InstagramLiveFeed posts, Reels, carousels
FacebookLivePosts, photos, photo carousels, videos, link previews
ThreadsLiveText, images, image carousels, videos
Google BusinessLiveLocal posts, updates, events, offers, CTA buttons

Platform names, Live status, and features exactly as listed in the captured source.

Frequently asked questions

How do I authenticate requests for the Create Post API?

Send the x-access-key header on every request. The health/auth check uses GET /v1/health/auth with that header, and the same header is used for profile creation, connecting an account, listing integrations, and creating posts.

Do I need to create a profile before connecting an account?

A profile is optional. If you create one, save its id and pass it as profileId when you connect an account and when you list integrations, so you can identify the integration created by that OAuth flow. If you skip the profile, omit profileId.

Where does accountId come from?

List integrations with GET /v1/connect/integrations, optionally filtered by profileId. The integration id in that response is the accountId value to place in each platforms entry when you create a post.

What is the difference between publishNow and scheduledFor?

Use publishNow set to true for immediate publishing. To schedule instead, provide scheduledFor and timezone and omit the immediate-publishing intent shown in the publish example.

What happens after I request the OAuth connect URL?

The connect request returns a url. Redirect the user to that url, and after authorization the account is connected to your project and bound to the profile if profileId was passed.

Check authentication
curl {{API_BASE_URL}}/v1/health/auth \
  -H "x-access-key: YOUR_API_KEY"
Create a profile
curl -X POST {{API_BASE_URL}}/v1/profiles \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Co" }'
Connect a Twitter/X account
curl "{{API_BASE_URL}}/v1/connect/twitter?profileId=65ab123" \
  -H "x-access-key: YOUR_API_KEY"
List integrations to get accountId
curl "{{API_BASE_URL}}/v1/connect/integrations?profileId=65ab123" \
  -H "x-access-key: YOUR_API_KEY"
Publish a post now
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "abc123"
      }
    ],
    "publishNow": true
  }'
Schedule a post
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "twitter", "accountId": "abc123" }
    ],
    "scheduledFor": "2026-03-29T09:00:00",
    "timezone": "America/New_York"
  }'