Aperçu de l'API

URL de base https://api.sofia-post.com/api · Document OpenAPI

Sofia API donne à votre code l’accès à votre compte Sofia : les établissements de vos Workspaces, leurs réseaux connectés, leur médiathèque, leurs publications et leurs statistiques. C’est une API REST en HTTPS ; les requêtes et les réponses sont en JSON. Elle permet de :

• Publier : maintenant, à une date ou en brouillon, sur un ou plusieurs réseaux à la fois.
• Vérifier avant de publier : une simulation vous dit si chaque réseau accepterait la publication, sans rien écrire.
• Gérer les médias : téléversez un fichier ou importez-le depuis une URL dans la médiathèque d’un établissement.
• Suivre les publications : lisez l’état de chaque réseau, son lien permanent ou la raison de l’échec. Un webhook signé peut aussi vous prévenir.
• Lire les statistiques : les derniers chiffres collectés par Sofia pour chaque compte connecté.
• Connecter des réseaux : créez un lien hébergé qui permet au propriétaire de connecter un réseau manquant.

SDK et intégrations

• CLI `sofia` : la CLI, publiée sur npm sous le nom sofia-post, pour piloter Sofia depuis un terminal.
• Serveur MCP : branchez Sofia à vos agents IA.
• Zapier : l’intégration Sofia se connecte avec votre clé personnelle. Elle offre les déclencheurs « Post Published » et « Post Failed », l’action « Create Post » (publier, programmer ou enregistrer un brouillon) et la recherche « Find Post ». Elle n’est pas encore soumise à l’annuaire public de Zapier.

Authentification

Chaque appel porte un jeton Bearer dans l’en-tête Authorization. Sofia relit les droits qui s’y rattachent à chaque appel : une personne retirée d’un Workspace, ou une autorisation révoquée, arrête le jeton dès la requête suivante.

Il y a deux façons de vous authentifier :

Clé API

Si vous automatisez votre propre Workspace, une clé personnelle suffit. Dans l’app Sofia, ouvrez Réglages › API, onglet Accès personnel, et créez une clé. Choisissez son nom, son expiration et ses permissions. La clé n’est affichée qu’une fois : copiez-la et gardez-la dans un coffre de secrets, jamais dans votre code.

Créez une clé dans Réglages › API › Accès personnel. Elle agit pour vous sur tous vos Workspaces : l’établissement que vous nommez détermine le Workspace, et votre rôle dans celui-ci décide de ce que la clé peut faire.

Envoyez la clé dans l’en-tête Authorization, comme jeton Bearer :

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

`GET /v1/me` vous indique pour qui la clé agit, ses Workspaces et ses permissions.

Un appel sans la permission (le scope) requise répond 403 insufficient_scope.

Jeton OAuth2

Pour un produit SaaS qui agit pour ses utilisateurs sur leurs propres Workspaces, enregistrez un client OAuth : chaque personne autorise votre application sur le Workspace de son choix. Les jetons d’accès OAuth commencent par sofia_live_at_…, durent une heure et s’utilisent de la même façon :

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

Vous créez une app à laquelle d’autres comptes Sofia se connectent ? Son flux authorization code avec PKCE, ses client credentials et ses scopes sont décrits dans OAuth2.

URL de base

Chaque endpoint se trouve sous une seule URL de base :

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

Limites de débit

Sofia API compte les requêtes sur trois fenêtres : 15 minutes, 24 heures et 30 jours.

En-têtes

Chaque réponse vous dit ce qu’il reste, au format IETF :

RateLimit: "15m";r=144;t=43, "24h";r=994;t=13543, "30d";r=9994;t=13543
RateLimit-Policy: "15m";q=150;w=900, "24h";q=1000;w=86400, "30d";q=10000;w=2592000

r est le nombre de requêtes restantes, t les secondes avant la réinitialisation de la fenêtre, q le quota et w la fenêtre en secondes.

Quand une fenêtre est pleine

La réponse est 429 rate_limit_exceeded, avec un en-tête Retry-After et la fenêtre épuisée dans details. Attendez ce délai avant de réessayer.

Utiliser l’API efficacement

• Enregistrez un webhook plutôt que d’interroger une publication en boucle.
• Utilisez limit jusqu’à 100 pour lire les listes en moins de pages.
• Mettez en cache ce qui change rarement : plateformes, établissements, comptes connectés.

Erreurs

Chaque erreur répond avec un statut HTTP et la même enveloppe JSON. code est le contrat que lit votre code ; message est écrit pour un humain et peut changer.

{
  "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 en dit plus : le champ refusé, la raison d’un réseau, la fenêtre de limite épuisée.
• docUrl mène à l’explication du code sur cette page.
• requestId identifie la requête : communiquez-le au support.

Codes d’erreur

Raisons d’une publication refusée

Un post_refused liste chaque raison dans details[].code :

Gérer les erreurs

• Branchez votre logique sur code, jamais sur message.
• Réessayez un 429 après Retry-After, et un 5xx avec un backoff exponentiel.
• Ne réessayez jamais un 4xx à l’identique : corrigez d’abord la requête.
• Journalisez requestId à chaque échec.

Pagination

Les listes (GET /v1/posts, GET /v1/media) sont renvoyées les plus récentes d’abord, une page à la fois. limit fixe la taille de page, de 1 à 100 (20 par défaut).

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

Passez nextCursor comme cursor pour lire la page suivante. Quand nextCursor est absent, vous avez atteint la fin.

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);

Un curseur est opaque : ne le construisez ni ne le modifiez jamais. Un curseur que Sofia n’a pas renvoyé répond 400 invalid_cursor.

Idempotence

Une erreur réseau peut vous laisser dans le doute sur la création d’une publication. Envoyez un en-tête Idempotency-Key avec POST /v1/posts et POST /v1/media, et réessayez avec la même clé : Sofia répond ce qu’elle a répondu la première fois, et ne crée rien en double.

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

• Utilisez une nouvelle clé aléatoire (un UUID) pour chaque nouvelle publication, et la même clé pour chaque nouvel essai de cette publication.
• La même clé avec un corps différent répond 422 idempotency_key_reused.
• Tant que la première requête est en cours, la même clé répond 409 idempotency_in_progress : réessayez un instant plus tard.

Mode test et simulation

Simulation. Ajoutez ?dry_run=true à POST /v1/posts : Sofia exécute les contrôles d’une vraie publication (les règles de chaque réseau, le compte connecté, les médias, la date et votre forfait) sans rien enregistrer ni envoyer. Le détail des réponses est sur la page Publier.

Mode test. Une application créée en mode test (jetons sofia_test_at_…) lit votre vrai Workspace mais n’y écrit jamais : ses publications sont simulées et jugées selon les mêmes règles, et toute écriture réelle répond 403 live_mode_required. Les clés et clients créés dans Réglages › API sont en mode live ; utilisez la simulation pour vérifier sans publier.