Social Accounts
List the social accounts connected to your login, so a script or an agent can point a Social Publish node at them without opening the app.
A Social Publish node posts to accounts by id, in config.accounts. This endpoint lists those ids, so a script or an agent holding an API key can target an account without opening the app.
List connected accounts
GET /api/v1/social/accounts
Scope: social:read. A full-access (*) key has it. None of the workflow scopes (workflows:read, workflows:write, workflows:execute, templates:execute) include it, so a key that builds or runs workflows needs social:read added to list accounts. A key without it gets 401, like every other endpoint. There are no parameters.
curl https://www.wireflow.ai/api/v1/social/accounts \
-H "Authorization: Bearer $WIREFLOW_API_KEY"
{
"data": {
"count": 2,
"accounts": [
{
"id": "native:cm1yt4k2",
"platform": "youtube",
"handle": "@mychannel",
"displayName": "My Channel",
"scope": "personal",
"publishable": true,
"analytics": "enabled",
"options": [
{
"name": "caption",
"kind": "longtext",
"description": "Caption for this platform instead of the default one."
},
{
"name": "title",
"kind": "text",
"description": "Video title, up to 100 characters. Defaults to the caption."
},
{
"name": "privacy",
"kind": "enum",
"description": "public, unlisted or private.",
"values": ["private", "unlisted", "public"]
},
{
"name": "scheduledPublishAt",
"kind": "datetime",
"description": "ISO 8601 time the platform makes the post public. Private until then; a time already past means public now."
},
{
"name": "tags",
"kind": "csv",
"description": "Tags as ONE comma-separated string, e.g. \"ai, video\", or a list of strings, e.g. [\"ai\", \"video\"]. YouTube keeps 500 characters of tags in total (commas count, and a tag with a space counts two more): the first tags that fit are kept and the rest are dropped."
},
{
"name": "thumbnailUrl",
"kind": "url",
"description": "Public https URL of a custom thumbnail. Needs a verified channel."
}
]
},
{
"id": "native:cm1th9x7",
"platform": "threads",
"handle": "@me",
"displayName": "Me",
"scope": "personal",
"publishable": true,
"analytics": "unsupported",
"options": [
{
"name": "caption",
"kind": "longtext",
"description": "Caption for this platform instead of the default one."
},
{
"name": "altText",
"kind": "longtext",
"description": "Image description for screen readers, used for every image."
}
]
}
]
}
}
This is the same payload the MCP list_social_accounts tool returns, under data. The permission differs: the MCP tool needs the opt-in social:publish grant (off by default, and only the account owner can tick it), while this endpoint needs the social:read API key scope.
| Field | Meaning |
|---|---|
id |
What goes in a node's config.accounts, or in the MCP publish_post tool's accountIds. Always starts with native:. |
platform |
youtube, threads, instagram, tiktok, facebook (one account per Page), linkedin, bluesky, mastodon or x (staff preview). |
handle, displayName |
As the platform shows them. |
scope, teamId, teamName |
personal for your own account. team for an account shared with a team you are an owner, admin or member of: anyone on that team can post to it, and teamId and teamName say which team. |
publishable |
false means the connection has to be re-authorized in the Wireflow app before it can post. |
analytics |
enabled, unsupported on that platform, or reconnect_required, in which case an analyticsNote says what to do. |
options |
The options you can set for this account under config.perPlatformOverrides.<platform>, each with its kind and, for an enum, its values. |
With nothing connected you get count: 0, an empty accounts list and a note, not an error.
What it covers
- Your own accounts, plus the accounts shared with every team you are an owner, admin or member of (
scope: "team"). No parameter picks a team: the list is everything you can post to. - Its own scope on purpose. The ids are what a Social Publish node posts to, so
workflows:read, the default for a new key, does not list them. - No tokens. A token, a refresh token or any other secret is never part of the response.
- Listing only. The account owner connects or reconnects an account, in a Social Publish node or from a connect link an agent asks for (the Social Publish page says how), and it shows up here on the next call. Posting is the Social Publish node, or the MCP
publish_posttool, which needs its ownsocial:publishpermission.
Point a node at an account
{
"config": {
"accounts": ["native:cm1yt4k2"],
"perPlatformOverrides": {
"youtube": { "title": "How it was made", "privacy": "unlisted" }
}
}
}
The keys each platform reads are on the Social Publish page.
Email capture on Instagram
Staff preview: only accounts on the auto-reply preview get these routes, and anyone else gets 404. Capture turns a live Instagram post's keyword DM into a short conversation that asks for an email and sends the asset. First make a list with POST /api/v1/social/leads/lists and { "name": "Reel guide", "accountId": "native:cm1yt4k2" }, passing the account the post is on, since a post only accepts a list from its own account (a team account's lists belong to the team). GET /api/v1/social/leads/lists?accountId=... lists them, each with a leadCount of leads of any status (subscribed, unsubscribed, bounced). Both need social:publish; social:read does not reach lead lists.
Then PUT /api/v1/social/posts/{id}/auto-reply with leadCapture: { mode: 'conversation', listId, asset: { id, title, url }, senderName, opener }, where listId is the id the list call returned. { mode: 'link' } turns it back into the plain link DM.
Content calendars
The Content Calendar combines plans with real social posts. A personal workspace or a team can own several calendars, one per client or brand. Each calendar has a name, color, timezone, linked social accounts and brief or brand board links. The page can show one calendar or overlay them all.
REST and MCP use the same server functions:
| Action | REST | MCP | Scope |
|---|---|---|---|
| List calendars | GET /api/v1/calendars |
list_calendars |
social:read |
| Create a calendar | POST /api/v1/calendars |
create_calendar |
social:publish |
| Edit a calendar | PATCH /api/v1/calendars/:id |
update_calendar |
social:publish |
| List entries | GET /api/v1/calendar |
list_calendar_entries |
social:read |
| Create an entry | POST /api/v1/calendar |
create_calendar_entry |
social:publish |
| Edit an entry | PATCH /api/v1/calendar/:id |
update_calendar_entry |
social:publish |
| Move an entry | POST /api/v1/calendar/:id/move |
move_calendar_entry |
social:publish |
| Delete an entry | DELETE /api/v1/calendar/:id |
delete_calendar_entry |
social:publish |
social:publish also covers calendar reads on REST and MCP. Default API keys have neither permission. Browser sessions use the same routes. Team owners, admins and members can edit; viewers can read. Every request checks membership server-side. A team calendar can use accounts connected by any current member. This does not grant permission to publish as another member.
Choose a calendar
Start with GET /api/v1/calendars. Omit teamId to use the active workspace. Pass teamId=null in a query or teamId: null in JSON for personal calendars, or name a team you belong to. The result is { data: { calendars, accounts, members, teamId, canEdit } }. Each calendar includes its id, version, name, color, timezone, accountIds and briefUrls. Accounts never include credentials.
Create a calendar with POST /api/v1/calendars:
{
"name": "Client launch",
"color": "#8B5CF6",
"timezone": "America/Los_Angeles",
"accountIds": ["native:cm1yt4k2"],
"briefUrls": ["https://www.wireflow.ai/flow/brand-board-id"],
"idempotencyKey": "client-launch-calendar-v1"
}
name, a six-digit hex color, an IANA timezone and idempotencyKey are required. accountIds and briefUrls default to empty lists. Accounts must belong to the selected workspace. Board links must be https Wireflow /flow/<id> URLs. Calendar PATCH takes expectedVersion, idempotencyKey and the settings to change; supplied account or board-link arrays replace the saved list.
Read a range
List with from and to as ISO timestamps with timezone offsets. The range includes from and excludes to, up to 93 days. For a local day, send local midnight and the following midnight with their respective offsets. Daylight saving days can be 23 or 25 hours.
GET /api/v1/calendar?calendarId=your-calendar-id&from=2026-10-18T00:00:00-07:00&to=2026-10-25T00:00:00-07:00&platform=instagram&status=scheduled
Omit calendarId for all calendars in the selected workspace. Filters status, platform, ownerId and accountId combine. The result is { data: { entries, calendars, accounts, members, teamId, canEdit } }. Entries include id, calendarId, version, timestamp, title, platform, account, status, caption, media and links. Their activity lists who changed which fields, the time, and the API key id or MCP client name when an agent made the change.
A linked post reports its real delivery status, including failed, publishing, published_private, sent_to_inbox and cancelled where applicable. sent_to_inbox means the creator must finish in the social app; it is not published.
Plan, edit and move content
Create an entry with POST /api/v1/calendar:
{
"calendarId": "your-calendar-id",
"title": "Behind the scenes",
"platform": "instagram",
"plannedAt": "2026-10-20T09:00:00-07:00",
"briefUrl": "https://www.wireflow.ai/flow/your-board-id",
"notes": "Film the new setup",
"status": "in_production",
"idempotencyKey": "behind-scenes-plan-v1"
}
calendarId, title, platform, plannedAt and idempotencyKey are required. Optional fields are accountId, briefUrl, notes, ownerId, status and postId. The owner defaults to the caller and must belong to the workspace. A plan's status is idea (default), in_production, ready, scheduled or published. An account must be linked to the calendar. postId attaches an existing real post returned by publish_post; its account and platform must match the entry.
PATCH changes only supplied entry fields. Send expectedVersion and idempotencyKey; null clears briefUrl or notes, and accountId on an unlinked plan. Linked postId and delivery fields stay locked unless the post failed with confirmation that nothing was posted and postId is explicitly cleared or replaced. Sending postId: null on a linked entry returns 409 linked_post_read_only unless the post failed with confirmation that nothing was posted. Active posts and uncertain outcomes stay locked. To move, POST { "calendarId": "destination-id", "expectedVersion": 3, "idempotencyKey": "move-behind-scenes-v1" } to /api/v1/calendar/:id/move, optionally adding plannedAt. You need edit access to both calendars, and the account and linked post must fit the destination. Moving a plan does not change a real post's delivery time.
DELETE takes a JSON body with expectedVersion and idempotencyKey. It removes the entry from the calendar, with no undo through the API. The linked real post stays scheduled or published; deletion does not cancel it.
Retries and concurrent edits
Every write requires an idempotencyKey of 8 to 200 characters in the JSON body. The Idempotency-Key header is not the calendar contract. Reuse the same key and identical request after a timeout to get the original result. Reusing a key with different content returns 409 idempotency_conflict.
Entry updates, moves and deletes, and calendar updates, require the expectedVersion returned by the latest list. If someone else changed the row, 409 version_conflict changes nothing. List again, reconcile the new values, then send the current version and a new idempotencyKey. Unknown fields are refused rather than ignored.
Link publishing to a plan
A plan does not schedule a post by itself. MCP publish_post can take plannedEntryId and expectedVersion together to publish to one matching account and link the queued post in the same transaction. Publishing still requires the caller's own connected account and existing publishing permission. A version conflict posts nothing. Use the normal publish idempotencyKey when retrying the same intended publish. After a definitive delivery failure confirms nothing was posted, fix the cause and use a fresh idempotencyKey with the current expectedVersion to retry the plan. This replaces its failed post link and keeps the historical post.
After linking, the entry shows the real post status and published URL. To attach a post that already exists, pass its postId when creating or updating the entry instead. An account can appear in personal and team calendars; a linked post is deduplicated within each calendar.
Related
- Post to Instagram
Post Reels, images and carousels to an Instagram Business or Creator account from a workflow, with Trial Reels, covers and collaborators.
- Social Publish
Publish a caption, with media or as text alone, to one or more connected social channels. Media is optional on Threads, Bluesky and Mastodon; Instagram, YouTube, LinkedIn and TikTok refuse a post without it. Posts go out at the time you set; posting cadence (min interval, max/day) and caption variation are checked and reported as warnings.
- Authentication
Create API keys, configure scopes, and authenticate requests to the Wireflow API.