Publish to social platforms — POST /v1/publish

Distribute content to the social platforms connected to your account. This is the distribution half of WideCast's output model (create → review → publish).

Provide exactly one content mode:

• topic_id — publish a WideCast video OR blog/social post you already created (via /v1/create_video or /v1/create_content). WideCast auto-detects article vs video. A video must be rendered first (/v1/export_video, wait for completed) else publish_not_ready (409).
• text — post arbitrary text (optionally with photo_urls).
• video_url — a direct video FILE url (.mp4/.mov/…) to download + publish. Requires title.

platforms defaults to all connected platforms of the chosen channel group. channel_group (integer, default 0 = primary) picks which channel group — a separate set of connected accounts, e.g. Vietnamese channels vs English channels — the post goes through; one call publishes through one group (list them with GET /v1/channel_groups). Charges 1 credit and posts publicly.

Publishing is asynchronous on the platform side: this returns the upstream request_ids immediately (202). Poll GET /v1/status/{request_id} for per-platform post URLs in result.posts. An article spanning text + photo platforms may return up to two request_ids.

Request fields

Response — 202 Accepted → poll /v1/status

{
  "object": "publish",
  "id": "abc123",
  "request_ids": ["abc123"],
  "status": "processing",
  "platforms": ["youtube", "x"],
  "skipped": [],
  "topic_id": "widecast7c0d4f8a9b1e2d3f",
  "content_kind": "video",
  "agent_note": "Recording step, do not skip: ..."
}

topic_id is present only when you published a WideCast video or article. content_kind says what went out: video, article, text or photo. agent_note is a short, generic instruction for agents that keep a local dashboard library: poll the status id, then record the post (see Recording what you publish); ignore it if you keep none.

Poll GET /v1/status/{request_id} (cadence 5s). For a publish id, type is "publish" and result.posts[] carries {platform, success, post_url, post_id, error}: - status == "completed" → all platforms reported back; check each result.posts[].success. - status == "failed" → the publish job failed upstream.

Recording what you publish

Once a publish-type status is completed or failed, the response also carries agent_note and result.library_record, a ready-to-file record ({kind, status, source: "widecast", title, urls, external}) for a local dashboard library: urls has one key per platform that went live (facebook, or facebook@2 for channel group 2), status is published only when at least one platform succeeded (a fully failed publish is draft), and external carries topic_id, request_id and channel_group. Pass it to <bridge> tool content import --json, or let <bridge> tool provider call --operation getStatus --path id=<request_id> file it. A post that is never recorded does not show up in that dashboard. If you keep no local library, ignore both fields.

SDK

from widecast import Widecast
c = Widecast(api_key="wc_live_…")
pub = c.publish(topic_id="widecast7c0d4f8a9b1e2d3f", platforms=["youtube", "x"])
status = c.get_status(pub["id"])      # poll for per-platform post URLs

const pub = await client.publish({ text: "We just shipped v2 — try it free today!" });
const status = await client.get_status(pub.id);

Errors