Publish a post

A post belongs to an establishment and goes out to one or more networks, its targets. Each target has its own text, media, format and state.

Post type: now, scheduled or draft

Two body fields decide when, and whether, the post goes out:

The body of a post

A target’s media

Each entry of targets[].media designates a media file from the library by its id, or a public https url with its type (image or video). Instagram and TikTok require a photo or a video. To add a media file to the library, see Import media.

Duplicating a post

There is no dedicated endpoint to duplicate a post: read it with `GET /v1/posts/{id}`, then send its content again in a new POST /v1/posts request.

Before sending it again, remove the fields that Sofia fills in herself. At a minimum:

• the post’s id and createdAt;
• the status of the post read (it summarizes the sending state): set the one you want, or omit it;
• in each target: state, publishedAt, permalink and error.

Keep establishmentId, and for each target platform and accountId. The read does not return the targets’ text or their media: supply them again. Finally set a new scheduledAt (or omit it to publish right away, or send "status": "draft").

Your first post

1. Check the connected networks

A post goes out through the accounts connected to the establishment. List them; if one is missing, create a connection link. See Connected accounts.

2. Add a media file

Instagram and TikTok require a photo or a video. Import one from a public https URL; Sofia downloads it into the library and returns its id. See Import media.

3. Check with a dry run

Add ?dry_run=true: Sofia judges each network by its real rules and the connected account, and writes nothing.

curl -X POST 'https://api.sofia-post.com/api/v1/posts?dry_run=true' \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "establishmentId": "'$ESTABLISHMENT_ID'",
    "targets": [
      { "platform": "instagram", "text": "Tarte tatin du jour", "media": [{ "id": "'$MEDIA_ID'" }] },
      { "platform": "facebook", "text": "Tarte tatin du jour", "media": [{ "id": "'$MEDIA_ID'" }] }
    ]
  }'

{
  "status": "ready",
  "dryRun": true,
  "targets": [
    { "platform": "instagram", "accountId": "fecd0904-…", "handle": "sof_ia_officiel", "state": "ready" },
    { "platform": "facebook", "accountId": "a423b3a4-…", "handle": "Sofia post", "state": "ready" }
  ]
}

4. Publish

Send the same body without dry_run, with an Idempotency-Key so that a retry never publishes twice. Without scheduledAt, the post goes out right away; with a future scheduledAt, it is scheduled.

curl -X POST https://api.sofia-post.com/api/v1/posts \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @post.json

5. Track it

The post answers publishing, then each network moves to published with its permanent link, or to failed with its reason. Read it with `GET /v1/posts/{id}`, or register a webhook to be notified.

Dry run

POST /v1/posts?dry_run=true runs the checks of a real post: each network’s rules, the connected account, the media, the date and your plan. It saves nothing and sends nothing.

Ready

When every network would accept the post, the response is 200 with status: "ready" and, for each target, the account that would publish.

Refused

Otherwise, the response is 422 post_refused, with one detail per reason. Each detail names its network, its code, and says what to fix.

{
  "error": {
    "code": "post_refused",
    "message": "The post would not be published: x: the text is too long (300 characters, at most 280)",
    "details": [
      {
        "platform": "x",
        "code": "caption_too_long",
        "max": 280,
        "actual": 300,
        "message": "x: the text is too long (300 characters, at most 280)"
      }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#post_refused"
  }
}

Each reason is listed in the errors.

For apps’ test mode, see Test mode and dry run. An Idempotency-Key also protects POST /v1/posts: see Idempotency.