Data model
The API uses the same words as the dashboard.
Workspace
Section titled “Workspace”Where a team’s Channels, Posts and plan live. A credential always acts in exactly one Workspace, so no request names one.
Channel
Section titled “Channel”One connected social account: a Facebook Page, an Instagram account, a TikTok account, a YouTube channel or a Threads profile.
| Field | |
|---|---|
id |
What you put in a Post’s channelIds |
network |
facebook, instagram, tiktok, youtube, x or threads |
name |
The account’s name, as the Network gave it |
state |
connected, needs_reconnect or not_connected |
canPostNow |
Its connection is healthy. Plan limits are judged when a Post is created |
What you write once. A Post has text, optional media, and one Variant per Channel it is aimed at.
| Field | |
|---|---|
id |
|
text |
What you wrote |
createdAt |
When it was made |
at |
Its earliest scheduled time, or when it was written |
via |
Made by an API key or an Authorized app: { kind, name, by }. null from the composer |
variants |
One per Channel |
Variant
Section titled “Variant”The Post as it goes to one Channel. Pubrivo fits the text to each Network, so Variants of one Post can differ.
| Field | |
|---|---|
id |
|
channelId, channelName, network |
Where it goes |
status |
Where it has got to — see below |
scheduledAt |
When it publishes. null for one published now |
failureReason |
Why it failed, when it did |
failureDetail |
What the Network said |
permalink |
The published post, once it is live |
mediaReady |
Every file is ready for this Network |
metrics |
A published YouTube video’s counts — see below. null elsewhere |
Metrics
Section titled “Metrics”On a Variant Pubrivo published to YouTube, metrics holds the counts YouTube reports for it, read
daily for its first 28 days and about monthly after:
{ asOf, counts: { views, likes, comments, shares, minutesWatched, averageViewDuration, averageViewPercentage, subscribersGained }, days }. days is the same counts by day, its latest
days lagging YouTube by up to three. A count is present only when YouTube reported it, and is
YouTube’s own figure. When there are none, metrics is { asOf, unavailable }, where
unavailable: "reconnect" means the Channel was connected before Pubrivo asked for YouTube
Analytics and must be connected again. Webhook payloads always carry null.
Status
Section titled “Status”A Variant moves through these:
scheduled— waiting for its time.publishing— being sent to the Network now.published— live;permalinkpoints at it.failed— it did not go out.failureReasonsays why:needs_reconnect,rejected_by_platform,media_problem,rate_limited,missed_window,platform_problemorunconfirmed.cancelled— cancelled before it started publishing.
unconfirmed means the Network may have published it but did not say so. Check the account before
trying again, or it may go out twice.