- Documentation
- API · Version 1.0
- Publications
Publications
On this page
A publication carries shared content and one target per chosen destination. Each target has its own status, its own text and its own outcome: Facebook can succeed while Instagram fails, and retrying Instagram does not republish to Facebook.
The resource
{
"data": {
"id": "pub_01k4b8y5t2v9h6p8w0y2z4b6c8",
"title": null,
"content": "Our new article is live.",
"link_url": "https://example.com/article",
"status": "scheduled",
"external_reference": "article-42",
"tags": ["PainAuLevain"],
"media": [
{ "id": "med_01k4b8z6u3w0j7q9x1z3a5c7e9", "alt_text": "A loaf of sourdough bread on a board." }
],
"scheduled_at": "2026-10-01T09:14:22+00:00",
"published_at": null,
"timezone": "Europe/Paris",
"targets": [
{
"destination_id": "dst_01k4b8x2q9r7f3m5t6v8w0y2z4",
"network": "facebook",
"provider": "meta",
"status": "pending",
"content": "Our new article is live.",
"link_url": "https://example.com/article",
"tags": ["PainAuLevain"],
"title": null,
"first_comment": null,
"media": [
{ "id": "med_01k4b8z6u3w0j7q9x1z3a5c7e9", "alt_text": "A loaf of sourdough bread on a board." }
],
"scheduled_at": null,
"published_at": null,
"external_url": null,
"attempts": 0,
"error": null,
"metrics": null
}
],
"created_at": "2026-10-01T09:14:22+00:00"
}
}
| Field | Meaning |
|---|---|
title |
Internal title. It is not sent to any network. |
content |
Shared text. |
link_url |
Shared link. |
status |
Aggregate status, see Statuses. |
external_reference |
Your own reference, as you sent it. |
tags |
Shared hashtags, formatted and without #. See The tags. |
media |
Shared images, in order, with their alt text. |
scheduled_at |
Planned departure date. Equals the moment of creation for an immediate publication, null for a draft or a publication submitted for approval. |
published_at |
Publication date. |
timezone |
Time zone of the publication, the brand's by default. |
targets[].destination_id |
The targeted destination. Link a target to its destination with this field. |
targets[].network |
The short name of the network (facebook, instagram, linkedin, threads, pinterest). |
targets[].provider |
The connection's provider: meta for Facebook and Instagram, otherwise the same name as the network. |
targets[].content |
The text actually sent to this destination. |
targets[].link_url, tags, title, first_comment, media |
The values actually kept for this destination: the network's override if there is one, the shared value otherwise, already filtered by what the network accepts. |
targets[].external_url |
The public URL of the post, once published. |
targets[].attempts |
Number of sending attempts. |
targets[].error |
{ "code", "message" } of the last error, or null. Our own refusals are in English; the network's keep its words (see Errors). |
targets[].metrics |
Statistics of the latest checkpoint read, or null. See Statistics. |
A target's values are fixed at creation: what leaves is what the target carries.
A target's error code and message come from the network and are passed on as is: rewording them would lose what lets you fix the problem.
POST /publications
Creates a publication and its targets.
Required scope: publications:create.
Required header: Idempotency-Key (see Idempotency).
| Field | Type | Required | Note |
|---|---|---|---|
destination_ids |
list of dst_… |
yes | At least one, 100 at most, no duplicates. |
content |
text | no | Shared text. |
title |
text (255) | no | Internal title, never published. |
link_url |
absolute URL (2048) | no | Ignored on a destination that does not accept links (Instagram). |
media |
list of {id, alt_text} objects |
no | 10 at most, no duplicates. alt_text: 1,000 characters at most. |
media_ids |
list of med_… |
no | Former form, without alt text. 10 at most. Mutually exclusive with media. |
tags |
list of texts | no | 30 at most, 100 characters each once formatted. |
first_comment |
text (8000) | no | Accepted, but no network publishes a first comment today: it is ignored. |
mastodon |
object | no | Settings of the Mastodon destinations: content_warning (text, 500, the warning the text is folded behind, counted in the server's limit), visibility (public, unlisted or private; when absent, the account's), language (fr, en, es, de, it, pt, nl, ca; when absent, the brand's). Any other key is refused. Returned in the publication's mastodon. |
scheduled_at |
ISO 8601 date | no | Must be in the future. |
timezone |
IANA time zone | no | Europe/Paris, America/Montreal… The brand's by default. |
mode |
draft, approval, scheduled, immediate |
no | Inferred if absent. |
overrides |
object keyed by network | no | See Per-network overrides. |
external_reference |
text (255) | no | Your reference, to find the publication again later. |
brand_id |
brd_… |
depends | Required if the client covers the whole workspace. |
A publication must carry text or an image, and each destination must receive one or the other once the overrides are applied.
The dates
scheduled_at follows the ISO 8601 standard: 2026-10-15T09:00:00+02:00, 2026-10-15T07:00Z or 2026-10-15T09:00. Seconds and offset are optional; without an offset, the time is read as UTC. Any other form — 15/10/2026, for example — is refused with 422, rather than read according to some guessed convention. The instant sent is kept, whatever the offset, and returned in UTC.
The mode
mode |
Effect | Initial status |
|---|---|---|
immediate |
Leaves on the next run of the scheduler, which runs every minute. | scheduled |
scheduled |
Leaves at scheduled_at, which becomes required. |
scheduled |
draft |
Saved, nothing leaves. To be released with publish. |
draft |
approval |
Submitted for the team's approval in the dashboard. | pending_approval |
Without mode, a date means scheduled and its absence means immediate: content sent without specifying anything leaves, it does not sit as a draft.
In draft or approval mode, scheduled_at is not saved: the departure date is chosen when releasing it, with publish. A date that is sent must still be in the future.
A publication in approval mode waits for a team member to approve it in the dashboard; the API does not approve. Once approved (status: "approved"), it is released with POST /publications/{id}/publish.
The images
media names images from the brand's library, in order, each with an optional alt text:
"media": [
{ "id": "med_01k4b8z6u3w0j7q9x1z3a5c7e9", "alt_text": "A loaf of sourdough bread on a board." }
]
media_ids(["med_…"]) is still accepted, without alt text. Sending both is refused.- The alt text is passed on to the networks that accept it (Facebook, Instagram, LinkedIn, Threads, Pinterest). Pinterest limits it to 500 characters.
- A deleted media item, even if it is still in the trash, can no longer be used.
- The number of images depends on the network: Facebook, Instagram, Threads and LinkedIn accept up to ten (a carousel on Instagram and Threads; the link of a Threads carousel is not sent; on LinkedIn, the images win over the link, as a single image does), Mastodon and Bluesky up to four, Pinterest one for now. See
capabilities.maximum_media_count. Images are sent in the order ofmedia.
The tags
tags carries hashtags, written freely: "pain au levain", "#PainAuLevain" or "pain-au-levain" all become PainAuLevain. Each word gets an initial capital, anything that is neither a letter nor a digit separates two words, and the # is removed: the resource returns the tags without it. A tag with nothing left ("!!!") is refused.
Each network places them in its own way:
| Network | Placement | Counted in the text limit |
|---|---|---|
| Facebook, Instagram, Pinterest | At the end of the text, after a blank line, #Tag separated by spaces. |
Yes |
| At the end of the text, as clickable hashtags. | Yes, in the form sent to LinkedIn, longer than #Tag. |
|
| Threads | The first tag becomes the post's topic (50 characters at most). The following ones are not sent. | No |
A tag that the text already carries as a hashtag (… our #PainAuLevain) is not repeated. On Instagram, the text's hashtags and the tags count together toward the limit of 30.
Per-network overrides
overrides replaces the shared values for a given network. It is keyed by network name, not by destination: an override applies to all destinations of that network present in the request.
"overrides": {
"linkedin": { "content": "A longer version for LinkedIn.", "tags": ["Boulangerie"] },
"instagram": { "content": "A caption for Instagram.", "tags": [] },
"pinterest": { "title": "Homemade sourdough bread" }
}
Allowed fields, by network:
| Network | content |
tags |
link_url |
media |
title |
first_comment |
|---|---|---|---|---|---|---|
facebook, linkedin, threads |
yes | yes | yes | yes | no | yes |
instagram |
yes | yes | no | yes | no | yes |
pinterest |
yes | yes | yes | yes | yes (100) | no |
- A key a network does not allow is refused with
422, on the override's field (« « instagram » does not accept: « link_url » »): it is never silently ignored. - An unknown network name is refused (« Unknown network: « linkedln ». »).
tags: []removes the hashtags for that network; an absent key keeps the shared value.mediareplaces the shared images for that network; an empty list is not an override.titleis the visible title of a Pin. The publication has no shared one: the internal title is never published.first_commentas an override is refused at validation, since no network publishes it today (see Refusals).- An override that targets a network absent from
destination_idsis ignored, media included. - Limits apply to the values actually sent to each destination, overrides included.
Example
curl -X POST https://quietsocial.dev/api/v1/publications \
-u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: article-42-publie-v1' \
-d '{
"content": "Our new article is live.",
"link_url": "https://example.com/article",
"destination_ids": ["dst_01k4b8x2q9r7f3m5t6v8w0y2z4", "dst_01k4b8x3r0s8g4n6u7w9x1z3a5"],
"media": [{"id": "med_01k4b8z6u3w0j7q9x1z3a5c7e9", "alt_text": "A loaf of sourdough bread."}],
"tags": ["pain au levain"],
"overrides": {"linkedin": {"content": "A version for LinkedIn."}},
"external_reference": "article-42"
}'
201 Created, with the full resource, targets included.
Refusals
A malformed body — missing field, wrong type, value outside the allowed list, date not in ISO 8601, override key not allowed — responds 422 with the validation envelope (see Errors).
A well-formed body that cannot become a publication responds 422 publication_not_publishable, and nothing is created. All destinations are examined: you receive all the errors at once, not one network at a time.
{
"error": {
"code": "publication_not_publishable",
"message": "“Instagram Fabrique” requires an image.",
"errors": [],
"destination_errors": {
"dst_01k4b8x4s1t9j5q7v8y0z2b4d6": ["“Instagram Fabrique” requires an image."]
}
}
}
errors carries what applies to the whole publication, destination_errors what applies to one destination, keyed by its identifier. message repeats the first error; read both lists. The messages are detailed in Errors.
A destination or media identifier that is unknown, or that belongs to another brand, is refused in errors, with the same message in both cases, and causes the whole publication to be refused: nothing leaves for the valid destinations of the same request.
Codes: 201, 400, 401, 403, 409, 422, 429.
GET /publications
The publications visible to the client, most recent first, with their targets.
Required scope: publications:read.
| Parameter | Type | Note |
|---|---|---|
brand_id |
brd_… |
Returns only the publications of this brand. A brand out of scope returns an empty list. |
external_reference |
text (255) | Returns only the publications carrying exactly this reference. |
status |
publication status | Returns only the publications in this status. An unknown value responds 422. |
per_page |
integer | Between 1 and 100, 25 by default. |
page |
integer |
curl "https://quietsocial.dev/api/v1/publications?external_reference=article-42" \
-u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET"
The external_reference filter gives you a way back from your identifier to ours: an automation that replays its business event can check whether it has already published, even after losing the pub_… identifier.
Codes: 200, 401, 403, 422, 429.
GET /publications/{id}
Required scope: publications:read.
Returns the full resource. This is the call to make after a publication.published webhook to get the public URLs in targets[].external_url.
Codes: 200, 401, 403, 404, 429.
POST /publications/{id}/publish
Releases a held publication: a draft, or an approved publication.
Required scope: publications:update. No idempotency key.
| Field | Type | Required | Note |
|---|---|---|---|
scheduled_at |
ISO 8601 date | no | Without a date, the publication leaves on the next run of the scheduler. |
curl -X POST https://quietsocial.dev/api/v1/publications/pub_01k4b8y5t2v9h6p8w0y2z4b6c8/publish \
-u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET" \
-H 'Content-Type: application/json' \
-d '{"scheduled_at": "2026-10-02T08:00:00+02:00"}'
200 OK, with the publication read again. Its status changes to scheduled; draft targets change to pending without a date, to scheduled with a date.
Refusals, all as 409 transition_not_allowed:
- the publication is awaiting approval (
pending_approval); - it is already scheduled (
scheduled): to change its time, move it from the dashboard's calendar; to stop it, cancel it; - it has already left or is finished;
- it has no destination;
scheduled_atis in the past;- the brand's monthly delivery quota is not enough for its targets.
A scheduled_at value that is not an ISO 8601 date responds 422.
Codes: 200, 401, 403, 404, 409, 422, 429.
POST /publications/{id}/cancel
Stops whatever can still be stopped.
Required scope: publications:cancel. No idempotency key.
Only targets in draft, pending_approval, pending, scheduled or queued are cancelled. A target already being handled (processing, uploading_media, waiting_for_media, publishing) may already have talked to the network: it is not cancelled.
The publication's status is derived from its targets. If one of them had already succeeded, the publication comes out partially_published, not cancelled. Read the returned status rather than expecting cancelled.
A publication that is already finished (published, partially_published, failed, cancelled) responds 409 transition_not_allowed.
Codes: 200, 401, 403, 404, 409, 429.
POST /publications/{id}/retry
Retries the failed targets.
Required scope: publications:retry. No idempotency key.
Targets in failed or requires_reconnect go back to pending, with their attempt counter reset to zero and their error cleared. A published target never leaves again.
A finished publication (failed, partially_published) whose targets leave again becomes scheduled once more, with the moment of the retry as its departure date: it can be cancelled again, and the calendar shows it on the day it leaves again.
Refusals, as 409 transition_not_allowed:
- no target needs retrying;
- a target to retry depends on a destination that cannot publish (connection to restore, destination disabled). Nothing is changed: first restore the connection in the dashboard.
A retry does not check the delivery quota: refusing to finish a half-sent publication would be worse than exceeding the cap by a few units.
Codes: 200, 401, 403, 404, 409, 429.
Statuses
Publication statuses
| Value | Meaning |
|---|---|
draft |
Saved, nothing leaves. |
pending_approval |
Awaiting approval by the team. |
approved |
Approved, not yet released. |
scheduled |
Scheduled, including for "now". |
queued |
Reserved; no publication takes this status today. |
processing |
At least one target is in progress or still waiting. |
published |
All targets are published. |
partially_published |
At least one target is published, another is not. |
failed |
No target is published. |
cancelled |
All targets are cancelled. |
The last four are terminal.
Target statuses
| Value | Meaning |
|---|---|
draft |
Held with its draft. |
pending_approval |
Awaiting approval. |
pending |
Waiting for the next run of the scheduler. |
scheduled |
Scheduled for a date. |
queued |
In the sending queue. |
processing |
Being handled. |
uploading_media |
Sending the image to the network. |
waiting_for_media |
The network is processing the media (most often a video): the target will be read again by itself. While a target is in this state, the publication cannot be cancelled, moved or deleted (409). |
publishing |
Publishing call in progress. |
published |
Published. external_url is filled in. |
failed |
Abandoned after its attempts, or refused. |
cancelled |
Cancelled. |
requires_reconnect |
The connection must be restored in the dashboard. |
Network-specific rules that are not in capabilities — image format and aspect ratio on Instagram, image width on Threads, image deleted since creation — are checked at sending time. A target that does not meet them changes to failed with error.code set to validation_failed and a message that names the rule; it is not retried.
A target makes up to five attempts. Only transient errors — network unavailable, network rate limit — are retried automatically: between two attempts, the target goes back to scheduled and keeps its last error in error. An authorization error puts it directly in requires_reconnect. failed and requires_reconnect are the two statuses that retry sends off again.
Statistics
targets[].metrics carries the counters of the latest checkpoint read with counters: around day 1, day 7 and day 30 after publication (three days later at most; a checkpoint missed beyond that is not caught up). It is null before the first reading, on a network whose statistics are not read, and when no reading has counters (post deleted, access not granted…). Today only Mastodon is read, without a token, for public or unlisted posts.
{
"checkpoint": 7,
"measured_at": "2026-10-08T05:40:12+00:00",
"favourites": 34,
"reblogs": 3,
"replies": 5,
"quotes": 1,
"impressions": null,
"reach": null,
"likes": 34,
"comments": 5,
"shares": 3,
"saves": null,
"clicks": null,
"video_views": null,
"limited_by": null
}
| Field | Meaning |
|---|---|
checkpoint |
The checkpoint: 1, 7 or 30 days after publication. |
measured_at |
When the reading was taken. |
impressions |
Times the post was displayed or viewed. |
reach |
Distinct people reached. |
likes |
Likes, reactions or favourites. |
comments |
Comments or replies. |
shares |
Shares, reposts or sends. |
quotes |
Quotes. |
saves |
Saves. |
clicks |
Outbound clicks or clicks on the content. |
video_views |
Video views. |
limited_by |
Why impressions, reach and clicks are missing while the rest was read: permission_missing (the account has not granted access to statistics; reconnecting reopens it for the next checkpoints), not_eligible (the network does not provide them for this account), not_measurable (this type of post has none). null otherwise. |
favourites, reblogs, replies |
Deprecated. Former Mastodon names of likes, shares and comments, with the same value, returned for every network. They stay in version 1 of the API; prefer the new names. |
A counter the network does not give is null, which is not 0: Mastodon gives neither impressions nor reach. More counters may be added to this object: ignore the keys you do not know.