Documentation API

Vue d'ensemble

L'API permet de publier immédiatement ou de programmer des posts sur les réseaux connectés à votre espace de travail Social by Start-Win. L'authentification se fait via une clé API (une par intégration, liée à un espace de travail).

• URL de base : https://social.start-win.fr
• Préfixe des routes : /api/v1/
• Format : JSON (Content-Type: application/json)

Prérequis

1. Créer un compte sur Social by Start-Win et connecter vos réseaux depuis Connexions.
2. Générer une clé API depuis Intégrations API (réservé aux administrateurs de l'espace).
3. Conserver la clé en lieu sûr — elle n'est affichée qu'une seule fois à la création.

Authentification

Envoyez votre clé dans chaque requête, de l'une des façons suivantes :

Authorization: Bearer sw_live_votre_cle_secrete

ou

X-Api-Key: sw_live_votre_cle_secrete

Les clés commencent par sw_live_. En cas de clé invalide ou révoquée, l'API répond 401 Unauthorized.

Réseaux supportés

Valeurs acceptées pour le champ networks :

• facebook
• instagram (image ou vidéo requise)
• linkedin
• x
• google (Google Business Profile)
• tiktok (vidéo requise)

Endpoints

GET /api/v1/connections

Liste les réseaux connectés à l'espace de travail.

curl -s "https://social.start-win.fr/api/v1/connections" \
  -H "Authorization: Bearer sw_live_..."

POST /api/v1/posts

Publie immédiatement ou programme un post.

Publication immédiate

curl -s -X POST "https://social.start-win.fr/api/v1/posts" \
  -H "Authorization: Bearer sw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Notre nouvelle offre est en ligne !",
    "networks": ["facebook", "linkedin"],
    "publishAt": "now"
  }'

Programmation

Utilisez publishAt ou scheduledAt avec une date ISO 8601 (ex. 2026-06-20T09:00:00+02:00). La date doit être au minimum 2 minutes dans le futur et au maximum 90 jours.

curl -s -X POST "https://social.start-win.fr/api/v1/posts" \
  -H "Authorization: Bearer sw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Rappel : webinaire demain à 14h",
    "networks": ["linkedin", "x"],
    "publishAt": "2026-06-20T09:00:00+02:00"
  }'

Corps de la requête

Médias

Deux options :

1. URL publique — le fichier doit être accessible en HTTPS :

   "media": [{ "url": "https://example.com/photo.jpg", "type": "image/jpeg" }]

2. Upload temporaire — uploadez d'abord via POST /api/v1/media, puis référencez le résultat :

   "media": [{ "tempFileName": "1739....jpg", "url": "...", "type": "image/jpeg" }]

Réponse (publication immédiate)

{
  "ok": true,
  "mode": "published",
  "text": "...",
  "mediaCount": 0,
  "results": [
    { "network": "facebook", "status": "published", "postId": "...", "message": "" }
  ],
  "summary": { "total": 2, "success": 2, "failed": 0 }
}

Réponse (programmation)

{
  "ok": true,
  "mode": "scheduled",
  "scheduled": {
    "id": "42",
    "text": "...",
    "networks": ["linkedin"],
    "scheduledAt": "2026-06-20T07:00:00.000Z",
    "status": "pending"
  }
}

POST /api/v1/media

Upload temporaire d'une image ou vidéo (base64). Fichier conservé ~20 minutes.

curl -s -X POST "https://social.start-win.fr/api/v1/media" \
  -H "Authorization: Bearer sw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "photo.jpg",
    "type": "image/jpeg",
    "contentBase64": "<contenu base64>"
  }'

Taille max : 100 Mo (configurable côté serveur).

GET /api/v1/posts/scheduled

Liste les publications programmées en attente.

Paramètre optionnel : limit (1–100, défaut 20).

GET /api/v1/posts/scheduled/:id

Détail d'une publication programmée.

DELETE /api/v1/posts/scheduled/:id

Annule une publication en attente.

GET /api/v1/posts/history

Historique des publications (publiées, programmées, etc.).

Paramètres : limit, q (recherche texte).

GET /api/v1/posts/optimal-slots

Suggère des créneaux de publication optimaux.

Paramètres : networks (liste séparée par des virgules, ex. linkedin,x), timezone (IANA, défaut Europe/Paris).

curl -s "https://social.start-win.fr/api/v1/posts/optimal-slots?networks=linkedin,facebook" \
  -H "Authorization: Bearer sw_live_..."

Intégration Claude & Cursor (MCP)

Le serveur MCP @start-win/social-mcp permet à Claude Desktop, Cursor ou tout client compatible MCP de publier et programmer vos posts en langage naturel.

Prérequis

1. Connectez vos réseaux depuis Connexions.
2. Générez une clé API depuis Intégrations API.
3. Installez le serveur MCP :

   npx -y @start-win/social-mcp

   ou clonez github.com/RobinCouet/social-mcp.

Configuration Cursor

Ajoutez dans ~/.cursor/mcp.json (ou Paramètres → MCP) :

{
  "mcpServers": {
    "social-start-win": {
      "command": "npx",
      "args": ["-y", "@start-win/social-mcp"],
      "env": {
        "SOCIAL_API_KEY": "sw_live_votre_cle",
        "SOCIAL_API_BASE": "https://social.start-win.fr"
      }
    }
  }
}

Configuration Claude Desktop

Ajoutez la même entrée dans ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou l'équivalent sur votre système.

Outils MCP disponibles

• list_connected_networks — réseaux connectés
• publish_post — publication immédiate
• schedule_post — programmation
• upload_media — upload image/vidéo (chemin local ou base64)
• list_scheduled_posts / get_scheduled_post / cancel_scheduled_post
• get_post_history — historique
• suggest_optimal_slots — créneaux optimaux

Exemple de prompt

Programme ce post sur LinkedIn et Facebook demain à 9h (Europe/Paris) :
« Notre nouvelle offre est en ligne ! Découvrez-la sur start-win.fr »

Claude utilisera les outils MCP pour vérifier les réseaux connectés, suggérer un créneau si besoin, puis programmer le post via l'API.

Codes d'erreur HTTP

• 400 — requête invalide (texte manquant, date incorrecte, etc.)
• 401 — clé API manquante ou invalide
• 402 — limite du forfait atteinte (posts/mois, etc.)
• 413 — média trop volumineux
• 500 — erreur serveur

Limites et bonnes pratiques

• Maximum 10 clés API actives par espace de travail.
• Les limites de votre forfait (posts/mois, réseaux) s'appliquent à l'API comme à l'interface.
• Révoquez immédiatement toute clé compromise.
• Ne commitez jamais une clé API dans un dépôt Git.
• Instagram et TikTok imposent des contraintes média (image/vidéo obligatoire).

Gestion des clés (interface web)

Les endpoints GET/POST/DELETE /api/workspaces/api-keys sont réservés à la session web (cookie) et permettent de créer ou révoquer des clés depuis Intégrations API.

Support

Questions ou besoin d'un plan agence avec quotas API dédiés ? Contactez robin@start-win.fr.