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.
| Method | Path | Header / Parameter | Purpose |
|---|---|---|---|
| GET | /v1/health/auth | x-access-key header | Check authentication |
| POST | /v1/profiles | x-access-key header; body field name | Create an optional profile |
| GET | /v1/connect/{platform} | x-access-key header; optional profileId query parameter | Get OAuth url for a platform |
| GET | /v1/connect/integrations | x-access-key header; optional profileId query parameter | List integrations and retrieve accountId |
| POST | /v1/posts | x-access-key header; Content-Type: application/json | Publish now or schedule a post |
Exact methods and paths from the captured source; origin shown as {{API_BASE_URL}}.
| Field | Location | Requiredness in shown examples | Notes |
|---|---|---|---|
| content | POST /v1/posts body | Shown in both examples | Post text |
| platforms | POST /v1/posts body | Shown in both examples | Array of platform targets |
| platforms[].platform | POST /v1/posts body | Shown in both examples | Example value: twitter |
| platforms[].accountId | POST /v1/posts body | Shown in both examples | Integration id from GET /v1/connect/integrations |
| publishNow | POST /v1/posts body | Shown in immediate example | Set to true to publish now |
| scheduledFor | POST /v1/posts body | Shown in schedule example | Scheduled date and time |
| timezone | POST /v1/posts body | Shown in schedule example | Example value: America/New_York |
| success | POST /v1/posts response | Returned | Overall result flag |
| status | POST /v1/posts response | Returned | Example value: published |
| postId | POST /v1/posts response | Returned | Identifier of the created post |
| platforms[].platformPostUrl | POST /v1/posts response | Returned per platform | URL of the published platform post |
Fields exactly as shown in the captured publish and schedule examples.
| Platform | Status | Features |
|---|---|---|
| Twitter/X | Live | Posts, threads, polls, images, videos, GIFs |
| YouTube | Live | Video uploads, Shorts, metadata |
| Live | Posts, images, videos | |
| Live | Pins with images | |
| Bluesky | Live | Text posts, images, link cards |
| TikTok | Live | Videos, photos, photo carousels |
| Live | Feed posts, Reels, carousels | |
| Live | Posts, photos, photo carousels, videos, link previews | |
| Threads | Live | Text, images, image carousels, videos |
| Google Business | Live | Local 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.
curl {{API_BASE_URL}}/v1/health/auth \
-H "x-access-key: YOUR_API_KEY"curl -X POST {{API_BASE_URL}}/v1/profiles \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Acme Co" }'curl "{{API_BASE_URL}}/v1/connect/twitter?profileId=65ab123" \
-H "x-access-key: YOUR_API_KEY"curl "{{API_BASE_URL}}/v1/connect/integrations?profileId=65ab123" \
-H "x-access-key: YOUR_API_KEY"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
}'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"
}'