SOSPosting Entwickler-API

Authentifizierung

Jede Anfrage trägt einen API-Schlüssel im Authorization-Header:

Authorization: Bearer sosp_<your key>

Schlüssel erstellen Sie in der Konsole unter Settings → API access (app.sosposting.com). Ein Schlüssel gehört zu dem Business, in dem er erstellt wurde: Er postet auf dessen verbundene Plattformen und verbraucht dessen Token-Guthaben. Der Schlüssel wird nur einmal bei der Erstellung angezeigt — behandeln Sie ihn wie ein Passwort; widerrufen können Sie ihn jederzeit auf demselben Bildschirm.

Basis-URL: https://app.sosposting.com. Anfragen und Antworten sind JSON. Ein API-Post kostet exakt dieselben Tokens wie derselbe Post aus dem Dashboard — siehe Preise.

POST /api/v1/posts — Beitrag erstellen

Ein Aufruf erreicht jede ausgewählte Plattform. Payload-Felder:

• type (erforderlich) — "reel", "social", "product" oder "blog".
• mediaUrl — öffentliche https://-URL des Bilds oder Videos (nutzen Sie den Presign-Endpunkt unten, wenn Sie Medien nicht selbst hosten).
• title, caption — Ihr Text; mit aktiviertem useAi macht die KI daraus plattformgerechte Captions, Titel und Hashtags.
• providers — Array wie ["INSTAGRAM","FACEBOOK","TIKTOK"]; Standard sind alle verbundenen Plattformen, die für den Beitragstyp infrage kommen.
• useAi — Standard true; mit false wird Ihr Text wörtlich veröffentlicht.
• scheduledAt — ISO-8601-Zeitstempel, um zu planen statt sofort zu veröffentlichen.

curl -X POST https://app.sosposting.com/api/v1/posts \
  -H "Authorization: Bearer sosp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "reel",
    "mediaUrl": "https://example.com/clip.mp4",
    "title": "Summer drop",
    "caption": "Our new summer collection is live",
    "providers": ["INSTAGRAM", "FACEBOOK", "YOUTUBE"],
    "useAi": true,
    "scheduledAt": "2026-08-01T09:00:00Z"
  }'

Antwortet mit 201, der Post-Id und einem Target pro Plattform:

{
  "id": "cmcz...",
  "scheduledAt": "2026-08-01T09:00:00.000Z",
  "targets": [
    { "id": "t1...", "status": "QUEUED" },
    { "id": "t2...", "status": "QUEUED" }
  ]
}

GET /api/v1/posts/:id — Status & Metriken abrufen

Fragen Sie den Beitrag ab, um Zustellung und Performance zu sehen. Der Zustellstatus kommt für jedes Target; Engagement-Metriken rufen wir nur bei Facebook, Instagram und YouTube ab — den Plattformen, deren APIs uns Insights pro Beitrag liefern. Metriken werden höchstens einmal pro Stunde bei Bedarf aktualisiert:

curl https://app.sosposting.com/api/v1/posts/cmcz... \
  -H "Authorization: Bearer sosp_..."

{
  "id": "cmcz...",
  "createdAt": "2026-07-13T10:00:00.000Z",
  "scheduledAt": null,
  "status": "POSTED",
  "targets": [
    {
      "provider": "INSTAGRAM",
      "status": "POSTED",
      "externalId": "1789...",
      "externalUrl": "https://www.instagram.com/p/...",
      "error": null,
      "metrics": { "views": 1200, "likes": 88, "comments": 7 }
    }
  ]
}

• Der Gesamt-status fasst die Targets zusammen: QUEUED, SCHEDULED (wartet auf die geplante Zeit), PROCESSING, POSTED, PARTIAL, FAILED oder SKIPPED.
• TikTok-Targets zeigen PENDING_USER, solange das Video in den TikTok-Entwürfen auf die manuelle Veröffentlichung wartet — es ist noch nicht öffentlich, daher ohne externalUrl.
• metrics wird nur bei FACEBOOK-, INSTAGRAM- und YOUTUBE-Targets gefüllt; alle anderen Plattformen (TikTok, Pinterest, LinkedIn, Threads, Bluesky, WordPress, Shopify) liefern immer metrics: null. Auch auf einer unterstützten Plattform ist der Wert null bis zur ersten Aktualisierung nach der Zustellung, und einzelne Felder fehlen, wenn die Plattform sie nicht meldet — shares gibt es nur bei Facebook, views nur bei Video-Beiträgen. metricsAt zeigt, wann die Metriken zuletzt aktualisiert wurden.
• Unbekannte oder fremde Post-Ids liefern 404.

POST /api/v1/media/presign — Medien ohne eigenen Bucket hochladen

Fordern Sie einen vorsignierten Upload an, senden Sie die Bytes per PUT und verwenden Sie die zurückgegebene publicUrl als mediaUrl beim Erstellen des Beitrags:

curl -X POST https://app.sosposting.com/api/v1/media/presign \
  -H "Authorization: Bearer sosp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "clip.mp4",
    "contentType": "video/mp4",
    "sizeBytes": 10485760
  }'

{
  "uploadUrl": "https://...r2.cloudflarestorage.com/...",
  "publicUrl": "https://media.../uploads/....mp4",
  "key": "uploads/....mp4"
}

curl -X PUT "<uploadUrl>" \
  -H "Content-Type: video/mp4" \
  --data-binary @clip.mp4

Limits: Bilder bis 25 MB, Videos bis 50 MB. sizeBytes ist Pflicht (sonst 400). Nicht unterstützte Content-Types werden mit 415 abgelehnt, zu große Dateien mit 413; Anfragen sind pro Unternehmen ratenbegrenzt (429).

Tokens & Fehler

• Gleiche Preise wie im Dashboard: Ein API-Post kostet dieselben Tokens wie der identische Post aus der Konsole. Zustellungen, die auf unserer Seite fehlschlagen, werden automatisch erstattet.
• Fehler liefern einen JSON-Body { "error": "...", "code": "..." } — der code ist ein stabiler, maschinenlesbarer Wert (z. B. insufficient_tokens, rate_limited) — mit üblichem Statuscode: 400 ungültige Anfrage, 401 ungültiger Schlüssel, 402 zu wenig Tokens, 404 nicht gefunden, 413/415 Medien-Limits, 429 zu viele Anfragen.

Gut zu wissen

• Verbinden Sie Ihre Plattformen einmal in der Konsole — die API veröffentlicht über dieselben Integrationen (auf Englisch).
• Mehrere Marken? Jedes Business hat seinen eigenen Schlüssel und seine verbundenen Konten, und die Businesses eines Kontos teilen sich ein gemeinsames Token-Guthaben — keine Gebühren pro Sitz oder Workspace.
• Die API ist unter /api/v1/ versioniert; Änderungen sind additiv.