Zum Inhalt springen
SPREVA

SPREVA startet bald.

Trag dich in die Warteliste ein und wir schreiben dir ein einziges Mal, sobald dein Konto bereit ist.

Kein Newsletter. Nur eine E-Mail, wenn SPREVA startet.

Referenz

REST-API

Erstelle, plane und veröffentliche Beiträge, lade Medien hoch und rufe Ergebnisse aus deinem eigenen Code ab. Die API folgt denselben Regeln und derselben Validierung wie SPREVA selbst.

Deine erste Anfrage

  1. 1

    Erstelle in SPREVA unter Entwicklung, dann API-Schlüssel einen API-Schlüssel. Für dieses Beispiel reicht ein Schlüssel mit Nur lesen; zum Veröffentlichen brauchst du einen mit Zugriff Veröffentlichen.

  2. 2

    Liste deine sozialen Konten:

    Terminal
    curl https://dev-app.spreva.ai/api/v1/social-accounts \
  -H "Authorization: Bearer spreva_sk_..."
  3. 3

    Lies die Antwort. Die Ergebnisse stehen in data, und die id eines Kontos gibst du als connectionId an, wenn du einen Beitrag dafür erstellst. Das Beispiel ist gekürzt: Das echte Objekt hat mehr Felder.

    JSON
    {
  "data": [
    {
      "id": "e81b3f52-0000-4000-8000-000000000005",
      "provider": "instagram",
      "displayName": "Acme Studio",
      "username": "acme",
      "status": "ACTIVE",
      "needsReconnect": false
    }
  ]
}

Grundlagen

Alle Endpunkte liegen unter dieser Adresse. Sende JSON, mit dem Schlüssel als Authorization: Bearer gefolgt vom Schlüssel.

URL
https://dev-app.spreva.ai/api/v1
  • Ein Schlüssel gehört zu einem Workspace und sieht nur diesen Workspace.
  • Limit: 120 Anfragen pro Minute je Person in einem Workspace, geteilt über alle Schlüssel, die sie erstellt hat. Darüber hinaus ist die Antwort ein 429, dessen Meldung sagt, wie viele Sekunden zu warten sind.
  • Fehler kommen in der Sprache des Accept-Language-Headers der Anfrage; ihr code ändert sich nie.
  • Aus einem Browser, der bei SPREVA angemeldet ist, sendest du statt eines Schlüssels x-workspace-id mit der Id des Workspaces.

Schlüssel und Berechtigungen

Ein Schlüssel handelt für die Person, die ihn erstellt hat, und kann nie mehr, als deren Rolle erlaubt. Inhaber und Administratoren erstellen Schlüssel, in einem Tarif mit API-Zugang, und der ganze Schlüssel wird nur einmal gezeigt. Jeder Schlüssel hat die Berechtigungen, die er bekommen hat:

posts:read
Beiträge, ihren Status, ihre Ergebnisse und Warteschlangen sehen
media:read
Die Medienbibliothek sehen
accounts:read
Die verbundenen sozialen Konten sehen
analytics:read
Statistiken sehen
posts:write
Beiträge erstellen, bearbeiten, planen, veröffentlichen und löschen und Warteschlangen verwalten
media:write
Medien hochladen, umbenennen und löschen
webhooks:write
Webhook-Endpunkte ansehen und hinzufügen
ai:write
KI verwenden. Bildunterschriften und Hashtags brauchen zusätzlich posts:write, Alt-Text und Bilder zusätzlich media:write

Nur lesen gibt die vier Leseberechtigungen. Veröffentlichen fügt posts:write, media:write und ai:write hinzu, genug für eine Automatisierung oder einen KI-Agenten. Ein 403 heißt, dass dem Schlüssel die Berechtigung fehlt oder die Rolle seines Erstellers sie nicht mehr erlaubt.

Fehler

Jeder Fehler hat dieselbe Form. Entscheide nach code, zeige message.

JSON
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key needs the posts:write scope for posts:create"
  }
}
400
INVALID_REQUEST · INVALID_JSON · WORKSPACE_REQUIRED

Körper oder Query passen nicht zum Endpunkt. details listet jedes Feld, das falsch ist. Ein Aufruf aus dem Browser ohne x-workspace-id bekommt WORKSPACE_REQUIRED.

401
UNAUTHENTICATED

Der Schlüssel fehlt, ist vertippt, widerrufen oder abgelaufen. Schicke „Authorization: Bearer <key>“.

402
ENTITLEMENT_EXCEEDED · AI_LIMIT_REACHED

Der Workspace hat keinen aktiven Tarif, keine KI-Credits mehr, oder sein Tarif enthält das nicht. Ein Inhaber kann unter Einstellungen, Abrechnung einen Tarif wählen oder Credits kaufen.

403
FORBIDDEN

Dem Schlüssel fehlt die Berechtigung für diese Anfrage, oder deine Rolle erlaubt sie nicht. Erstelle einen Schlüssel mit mehr Zugriff.

404
NOT_FOUND

So ein Objekt gibt es in diesem Workspace nicht. Ein Schlüssel sieht immer nur den Workspace, in dem er erstellt wurde.

409
CONCURRENT_MODIFICATION · INVALID_STATE_TRANSITION · CONFLICT · AI_NOT_CONFIGURED

Der Beitrag hat sich geändert, seit du ihn gelesen hast, er ist in einem Zustand, der das nicht erlaubt (einen veröffentlichten Beitrag veröffentlichen), eine Datei, die du löschen willst, wird noch in einem Beitrag verwendet, oder die KI ist auf dieser Installation nicht eingerichtet. Hole ihn neu und versuche es erneut.

422
VALIDATION_FAILED · PROVIDER_VALIDATION_FAILED · AI_REFUSED

Der Inhalt passt nicht zum Konto, in das er geht, oder eine KI-Anfrage wurde abgelehnt. GET /providers listet die Regeln jedes Netzwerks.

429
RATE_LIMITED · AI_BUSY

Mehr als 120 Anfragen in einer Minute von dir in diesem Workspace, oder zu viele KI-Anfragen auf einmal. Bei RATE_LIMITED sagt die Meldung, wie viele Sekunden zu warten sind; bei AI_BUSY warte einen Moment.

500
INTERNAL

Beim Bearbeiten der Anfrage ist etwas fehlgeschlagen, in SPREVA oder bei einem sozialen Netzwerk. Versuche es in Kürze erneut.

503
AI_UNAVAILABLE

Der KI-Anbieter ist gerade nicht erreichbar. Versuche es in Kürze erneut.

Endpunkte

Pfade sind relativ zur Basis-URL. Das OpenAPI-Dokument beschreibt jeden Körper und Parameter, und du kannst daraus einen Client erzeugen:

URL
https://dev-app.spreva.ai/api/openapi.json

Soziale Konten und Netzwerke

  • get /social-accountsDie verbundenen sozialen Konten.
  • get /providersDie Regeln jedes Netzwerks: Formate, Platzierungen und Limits.

Beiträge

  • get /postsBeiträge, gefiltert nach Status, Zeitraum, Konto, Netzwerk oder Kampagne.
  • post /postsEinen Entwurf für ein oder mehrere Konten erstellen.
  • get /posts/{id}Ein Beitrag mit seinen Konten, seiner Prüfung und seinen Medien.
  • patch /posts/{id}Einen Beitrag ändern. Sende die version, die du gelesen hast; hat er sich seitdem geändert, ist die Antwort 409.
  • delete /posts/{id}Einen Beitrag löschen.
  • post /posts/{id}/publishJetzt veröffentlichen. Die Antwort ist 202: Das Ergebnis siehst du am Beitrag oder über einen Webhook.
  • post /posts/{id}/scheduleIhn für eine Uhrzeit planen, mit einer Zeitzone.
  • post /posts/{id}/queueIhn in den nächsten freien Platz einer Warteschlange legen.
  • post /posts/{id}/retryEin fehlgeschlagenes Konto erneut versuchen.

Medien

  • get /mediaDie Bibliothek, mit Suche und Filtern.
  • post /media/uploadsEinen Upload starten: Die Antwort sagt, wohin die Datei geht.
  • post /media/uploads/{id}/completeEinen Upload abschließen. Danach wird die Datei geprüft und verarbeitet.
  • get /media/{id}Eine Datei, mit ihrem Status und dem, was über sie bekannt ist.
  • delete /media/{id}Eine Datei löschen. Eine Datei, die noch in einem Beitrag steckt, antwortet 409.
  • put /media/{id}/alt-textDen Alternativtext einer Datei speichern oder leeren.
  • post /media/{id}/alt-text/suggestionAlternativtext mit KI vorschlagen, ohne ihn zu speichern.

Statistiken

  • get /analyticsErgebnisse für einen Zeitraum.
  • get /analytics/exportDieselben Ergebnisse als CSV-Datei.

Warteschlangen

  • get /queuesDie Warteschlangen.
  • post /queuesEine Warteschlange mit ihren wöchentlichen Zeiten erstellen.
  • patch /queues/{id}Eine Warteschlange ändern.
  • delete /queues/{id}Eine Warteschlange löschen.

Webhooks

  • get /webhooksDie Webhook-Endpunkte.
  • post /webhooksEinen Endpunkt hinzufügen. Die Antwort enthält sein Geheimnis, nur dieses eine Mal.

KI

  • get /aiOb KI verfügbar ist, wie viele Credits übrig sind und was jede Aktion kostet.
  • post /ai/captionsNeue Fassungen einer Bildunterschrift, Übersetzungen oder Hashtags vorschlagen, ohne sie zu speichern.
  • post /ai/imagesEin Bild generieren. Frage GET /media/{id} ab, bis es fertig ist.