Zum Inhalt springen

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://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://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
clippers:read
Dein Clipper-Programm, seine Konten und ihre Zahlen 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
clippers:write
Clipper einrichten und Konten freigeben, ablehnen oder entfernen

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.

Weder ein Schlüssel noch ein Agent kann je einen Beitrag freigeben: Verlangt ein Workspace eine Freigabe, gibt nur ein Mensch frei, in SPREVA.

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, CLIPPER_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, REVIEW_REQUIRED, CLIPPER_PROGRAM_CLOSED, CLIPPER_ACCOUNT_ELSEWHERE

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. REVIEW_REQUIRED ist etwas anderes: Der Workspace verlangt eine Freigabe, bevor Beiträge rausgehen. Schick den Beitrag dann mit POST /posts/{id}/review zur Prüfung, statt es erneut zu versuchen.

422
VALIDATION_FAILED, PROVIDER_VALIDATION_FAILED, AI_REFUSED, CLIPPER_RULE_NEEDS_WORDS, CLIPPER_NETWORK_NOT_ALLOWED, CLIPPER_NAME_RULE

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://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}/reviewIhn mit einer Zeit oder einer Warteschlange zur Prüfung schicken; er geht raus, sobald er freigegeben ist.
  • 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.
  • post /posts/{id}/metrics/refreshDie Zahlen eines Beitrags sofort auslesen, in jedem Netzwerk, in dem er erschienen ist. 429 mit Retry-After, solange die letzte Aktualisierung keine fünf Minuten her ist.
  • post /social-accounts/{id}/metrics/refreshDie Follower eines Kontos sofort auslesen. Dieselbe Wartezeit von fünf Minuten wie bei einem Beitrag.

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.

Clipper

  • get /clippersDie Konten, die mit deinem Clipper-Programm verknüpft sind, mit ihren Aufrufen in einem Zeitraum.
  • get /clippers/statsDie Aufrufe deiner Clipper in einem Zeitraum: die Summe, je Netzwerk, je Tag und, wenn du danach fragst, je Konto.
  • get /clippers/calendarWas deine Clipper in einem Zeitraum in SPREVA geplant haben und was so veröffentlicht wurde, die frühesten zuerst.
  • get /clippers/exportJedes Konto, das dein Programm je hatte, mit seinen Aufrufen in einem Zeitraum, als CSV-Datei.
  • get /clippers/{id}Ein verknüpftes Konto mit seinen Aufrufen in einem Zeitraum.
  • get /clippers/{id}/postsSeine Beiträge seit der Verknüpfung, die neuesten zuerst, mit den Aufrufen, die das Netzwerk meldet.
  • post /clippers/{id}/approveEin wartendes Konto freigeben. Seine Beiträge zählen ab jetzt.
  • post /clippers/{id}/declineEin wartendes Konto ablehnen, mit einem Grund, den der Clipper liest, wenn du einen angibst.
  • post /clippers/{id}/removeEin Konto entfernen, mit einem Grund, den der Clipper liest, wenn du einen angibst. Was es gebracht hat, bleibt in deinen Summen.
  • get /clippers/programDein Programm: sein Link, seine Namensregel und wie Konten freigegeben werden.
  • post /clippers/programDein Programm einrichten und den Link bekommen, den du mit Clippern teilst.
  • patch /clippers/programDas Programm ändern, keine neuen Konten mehr annehmen, es pausieren oder schließen. Mit dem Schließen enden alle Verknüpfungen.