Posts

Publish a post

Live apps publish at once, schedule with a date or save a draft; test apps only simulate. With ?dry_run=true it checks everything and writes nothing.

POSThttps://api.sofia-post.com/api/v1/posts

POST/v1/posts

API key or access tokenKept in this tab only, and sent only to api.sofia-post.com.dry_run (query)Idempotency-Key (header)Request body

This request acts on your real account.

curl -X POST 'https://api.sofia-post.com/api/v1/posts' \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"establishmentId":"cmvy2k3m40001ms4rest00000","targets":[{"platform":"instagram","text":"Tarte tatin du jour","format":"post","accountId":"cmvy2k3m40001ms4rig000000"}],"scheduledAt":"2026-11-02T10:00:00.000Z"}'

Authorizations

Authorizationstringrequired
Your personal key or OAuth access token, sent as Bearer <token>.

Query parameters

dry_runstring
true: runs every check the send would run (network rules, accounts, media, creation, live subscription) and writes nothing. Returns 200 ready or 422 post_refused.
Allowed values: truefalse

Headers

Idempotency-Keystring
Replayed with the same body, the request returns the same response without creating a second post. A dry run does not consume the key.

Body

application/json

establishmentIdstringrequired
Establishment, in the Workspace of the token grant (GET /v1/establishments)
targetsobject[]required
One network per target
Show child attributes
- platformstringrequired
  Targeted network
  Allowed values: instagramfacebookxlinkedintiktok
- textstringrequired
  Caption published on this network
- mediaobject[]
  Attached media
  Show child attributes
  - idstring
    Identifier of a media of the establishment library (otherwise url and type)
  - urlstring
    Public address of the media (https in live); without an identifier
  - typestring
    Kind of the media given by address
    Allowed values: imagevideo
- formatstring
  Format (post, reel, story, carousel...); by default, the one the network would serve
- accountIdstring
  Live: the connected account that publishes, when the establishment has several on this network (GET /v1/establishments/:id/accounts)
scheduledAtstring<date-time>
Scheduling date (ISO 8601), in the future; absent: publish immediately. Not allowed with status draft
statusstring
draft: a draft (live only), created without a date, nothing is sent; PATCH /v1/posts/:id schedules it
Allowed values: draft

Response

200application/json

Dry run: every check passed.

statusstringrequired
Always ready
Allowed values: ready
dryRunbooleanrequired
Always true
Allowed values: true
targetsobject[]required
The checked targets
Show child attributes
- platformstringrequired
  Network of the target
- statestringrequired
  Always ready
  Allowed values: ready
- accountIdstring
  Live: the account that would publish
- handlestring
  Live: its displayed handle

201application/json

Live: publishing or scheduled. Test: simulated.

idstringrequired
Identifier of the post, to read back with GET /v1/posts/:id
statusstringrequired
State of the post at creation
Allowed values: draftpublishingscheduled
establishmentIdstringrequired
Establishment of the post
targetsobject[]required
The targets of the post
Show child attributes
- platformstringrequired
  Network of the target
- accountIdstringrequired
  The account that publishes
- statestringrequired
  State of the target at creation
  Allowed values: draftpublishingscheduledfailed
scheduledAtstring<date-time>
When the post is scheduled to be published

400

Malformed body.

401

The token is missing, unknown, expired or revoked.

402

subscription_required (live, dry run included).

403

The token does not have the posts:write scope.

404

establishment_not_found: outside the Workspace of the token.

422application/json

post_refused: a network, the establishment or the creation would refuse; media_import_refused (live) with its reason; idempotency_key_reused.

4XXapplication/json

Any other error, in the error envelope.