API Overview

SDKs and integrations

Authentication

There are two ways to authenticate with the Sofia API:

API key

Create a key in Settings › API, Personal access tab, then include it in the Authorization header:

curl https://api.sofia-post.com/api/v1/establishments \
  -H "Authorization: Bearer sofia_pk_live_…"

A personal key acts for you on all your Workspaces, with the rights your role gives you in each. It is shown only once: keep it in a secrets vault, never in your code. `GET /v1/me` tells you who it acts for and what it may do.

OAuth2 token

If you are building an app for other Sofia users, use OAuth2 to get tokens that act on their behalf. OAuth tokens start with sofia_live_at_, last one hour and are used the same way:

curl https://api.sofia-post.com/api/v1/establishments \
  -H "Authorization: Bearer sofia_live_at_…"

Base URL

Every endpoint lives under a single base URL:

https://api.sofia-post.com/api/v1

The machine-readable contract of every endpoint is the OpenAPI document.

Rate limits

The rate limit does not depend on your subscription plan: plans cap establishments, connected networks and campaigns instead (see Limits). All your personal keys share the counters of your account, whatever the Workspace, and so does the Sofia CLI. Each OAuth client has its own, which grow with the people who authorized it, up to 1,000. Every caller has two buckets — its writes (POST, PATCH, DELETE) and its reads (GET) — over fixed windows:

Every response tells you what is left of the bucket it spent, in the IETF format — here, a write:

RateLimit: "1h";r=97;t=1843, "24h";r=994;t=13543
RateLimit-Policy: "1h";q=100;w=3600, "24h";q=1000;w=86400

r is the number of requests remaining, t the seconds before the window resets, q the quota and w the window in seconds.

A full window answers 429 rate_limit_exceeded, with a Retry-After header and the full window in details: wait that long before trying again. To spend fewer requests, register a webhook rather than polling a post, and read lists with limit=100.

Errors

Every error answers with an HTTP status and the same JSON envelope. code is the contract your code reads; message is written for a human and may change.

This table covers the usual statuses: every code the API returns, with its status, is listed in [Error codes](#error-codes).

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": [
      { "field": "targets[0].text", "code": "required", "message": "targets[0].text is required" }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#invalid_request",
    "requestId": "2aab5943-6333-4caf-8478-25a85ebd4abf"
  }
}

• details says more: the rejected field, a network’s reason, the exhausted rate-limit window.
• docUrl leads to the explanation of the code on this page.
• requestId identifies the request: give it to support.

Error codes

Reasons a post is refused

A post_refused lists each reason in details[].code:

Terminology

Pagination

Lists (GET /v1/posts, GET /v1/media) are returned most recent first, one page at a time. limit sets the page size, from 1 to 100 (20 by default).

{
  "data": [ … ],
  "nextCursor": "WyIyMDI2LTEwLTI3VDE1OjExOjU5LjAxN1oiLCIx…"
}

Pass nextCursor as cursor to read the next page. When nextCursor is absent, you have reached the end.

let cursor;
do {
  const url = new URL('https://api.sofia-post.com/api/v1/posts');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);
  const page = await globalThis.fetch(url, { headers: { Authorization: `Bearer ${key}` } }).then((r) => r.json());
  handle(page.data);
  cursor = page.nextCursor;
} while (cursor);

A cursor is opaque: never build or modify one. A cursor that Sofia did not return answers 400 invalid_cursor.

Idempotency

A network error can leave you unsure whether a post was created. Send an Idempotency-Key header with POST /v1/posts and POST /v1/media, and retry with the same key: Sofia answers what it answered the first time, and creates nothing twice.

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: $IDEMPOTENCY_KEY" \
  -d @post.json

• Use a new random key (a UUID) for each new post, and the same key for each retry of that post.
• The same key with a different body answers 422 idempotency_key_reused.
• While the first request is still running, the same key answers 409 idempotency_in_progress: try again a moment later.

Test mode and dry run

Dry run. Add ?dry_run=true to POST /v1/posts: Sofia runs the checks of a real post (each network’s rules, the connected account, the media, the date and your plan) without saving or sending anything. The detail of the responses is on the Publish page.

Test mode. An application created in test mode (sofia_test_at_… tokens) reads your real Workspace but never writes to it: its posts are simulated and judged by the same rules, and any real write answers 403 live_mode_required. Keys and clients created in Settings › API are in live mode; use the dry run to check without publishing.

Supported platforms

Each target names its network in platform. format picks one of the network’s formats, and the default one when it is absent. GET /v1/platforms returns these rules live, with the accepted media types.

Quick examples

Schedule a post on Instagram

{
  "establishmentId": "your-establishment-id",
  "scheduledAt": "2026-12-14T10:00:00.000Z",
  "targets": [
    {
      "platform": "instagram",
      "text": "Tarte tatin du jour 🍎",
      "media": [{ "id": "your-media-id" }]
    }
  ]
}

Post right away on LinkedIn

{
  "establishmentId": "your-establishment-id",
  "targets": [
    {
      "platform": "linkedin",
      "text": "Nous recrutons un second de cuisine ! 🎉"
    }
  ]
}

Upload an image and post it on Instagram

# Step 1: upload the image
curl -X POST https://api.sofia-post.com/api/v1/media \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -F "establishmentId=your-establishment-id" \
  -F "file=@photo.jpg"

# Response: { "id": "your-media-id", "type": "image", "url": "https://…" }

# Step 2: create the post with the uploaded image
curl -X POST https://api.sofia-post.com/api/v1/posts \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "establishmentId": "your-establishment-id",
    "targets": [{
      "platform": "instagram",
      "format": "post",
      "text": "Coucher de soleil sur la terrasse 🌅",
      "media": [{ "id": "your-media-id" }]
    }]
  }'

Save a draft for several networks

{
  "establishmentId": "your-establishment-id",
  "status": "draft",
  "targets": [
    {
      "platform": "facebook",
      "text": "Menu de la semaine : tarte tatin et café"
    },
    {
      "platform": "x",
      "text": "Menu de la semaine ☕"
    }
  ]
}