Aller au contenu
SPREVA

Référence

API REST

Créez, programmez et publiez des publications, importez des médias et lisez les résultats depuis votre propre code. L’API suit les mêmes règles et les mêmes vérifications que SPREVA lui-même.

Votre première requête

  1. 1

    Créez une clé API dans SPREVA sous Développeurs, puis Clés API. Une clé Lecture seule suffit pour cet exemple ; publier nécessite une clé avec l’accès Publication.

  2. 2

    Listez vos comptes sociaux :

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

    Lisez la réponse. Les résultats se trouvent dans data, et l’id d’un compte est ce que vous passez comme connectionId quand vous créez une publication pour ce compte. L’exemple est abrégé : l’objet réel contient davantage de champs.

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

Principes de base

Tous les endpoints se trouvent sous cette adresse. Envoyez du JSON, avec la clé sous la forme Authorization: Bearer suivi de la clé.

URL
https://app.spreva.ai/api/v1
  • Une clé appartient à un seul espace de travail et ne voit jamais que celui-ci.
  • Limite : 120 requêtes par minute pour chaque personne dans un espace de travail, partagées entre toutes les clés qu’elle a créées. Au-delà, la réponse est un 429 dont le message indique combien de secondes attendre.
  • Les erreurs sont renvoyées dans la langue de l’en-tête Accept-Language de la requête ; leur code ne change jamais.
  • Depuis un navigateur connecté à SPREVA, envoyez x-workspace-id avec l’identifiant de l’espace de travail au lieu d’une clé.

Clés et autorisations

Une clé agit pour la personne qui l’a créée et ne peut jamais faire plus que ce que permet le rôle de cette personne. Les propriétaires et les administrateurs créent les clés, avec un forfait qui inclut l’accès à l’API, et la clé complète n’est affichée qu’une seule fois. Chaque clé a les autorisations qui lui ont été données :

posts:read
Voir les publications, leur statut, leurs résultats et les files d’attente
media:read
Voir la médiathèque
accounts:read
Voir les comptes sociaux connectés
analytics:read
Voir les statistiques
posts:write
Créer, modifier, programmer, publier et supprimer des publications, et gérer les files d’attente
media:write
Importer, renommer et supprimer des médias
webhooks:write
Voir et ajouter des endpoints de webhook
ai:write
Utiliser l’IA. Les légendes et les hashtags nécessitent aussi posts:write ; le texte alternatif et les images nécessitent aussi media:write

Lecture seule donne les quatre autorisations de lecture. Publication ajoute posts:write, media:write et ai:write, ce qui suffit pour une automatisation ou un agent IA. Un 403 signifie que la clé n’a pas l’autorisation, ou que le rôle de la personne qui l’a créée ne le permet plus.

Ni une clé ni un agent ne peuvent jamais approuver une publication : là où un espace de travail exige une approbation, seule une personne approuve, dans SPREVA.

Erreurs

Toutes les erreurs ont la même forme. Basez votre logique sur code, affichez message.

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

Le corps ou les paramètres de la requête ne correspondent pas à l’endpoint. details liste chaque champ incorrect. Un appel depuis un navigateur sans x-workspace-id reçoit WORKSPACE_REQUIRED.

401
UNAUTHENTICATED

La clé est absente, mal saisie, révoquée ou expirée. Envoyez « Authorization: Bearer <key> ».

402
ENTITLEMENT_EXCEEDED, AI_LIMIT_REACHED

L’espace de travail n’a aucun forfait en vigueur, n’a plus de crédits IA, ou son forfait n’inclut pas cette fonction. Un propriétaire peut choisir un forfait ou acheter des crédits sous Paramètres, puis Facturation.

403
FORBIDDEN

La clé n’a pas l’autorisation nécessaire pour cette requête, ou votre rôle ne le permet pas. Créez une clé avec davantage d’accès.

404
NOT_FOUND

Aucun objet de ce type dans cet espace de travail. Une clé ne voit jamais que l’espace de travail dans lequel elle a été créée.

409
CONCURRENT_MODIFICATION, INVALID_STATE_TRANSITION, CONFLICT, AI_NOT_CONFIGURED, REVIEW_REQUIRED

La publication a changé depuis que vous l’avez lue, elle est dans un état qui ne le permet pas (mettre en ligne une publication déjà publiée), un fichier que vous supprimez est encore utilisé par une publication, ou l’IA n’est pas configurée sur cette installation. Récupérez-la de nouveau et réessayez. REVIEW_REQUIRED est différent : l’espace de travail exige une approbation avant que les publications partent, envoyez donc la publication en relecture avec POST /posts/{id}/review au lieu de réessayer.

422
VALIDATION_FAILED, PROVIDER_VALIDATION_FAILED, AI_REFUSED

Le contenu ne convient pas au compte auquel il est destiné, ou une demande à l’IA a été refusée. GET /providers liste les règles de chaque réseau.

429
RATE_LIMITED, AI_BUSY

Plus de 120 requêtes en une minute de votre part dans cet espace de travail, ou trop de demandes à l’IA en même temps. Pour RATE_LIMITED, le message indique combien de secondes attendre ; pour AI_BUSY, patientez un instant.

500
INTERNAL

Une erreur s’est produite pendant le traitement de la requête, dans SPREVA ou sur un réseau social. Réessayez dans un instant.

503
AI_UNAVAILABLE

Le fournisseur d’IA est indisponible pour le moment. Réessayez dans un instant.

Endpoints

Les chemins sont relatifs à l’URL de base. Le document OpenAPI décrit chaque corps de requête et chaque paramètre, et vous pouvez en générer un client :

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

Comptes sociaux et réseaux

  • get /social-accountsLes comptes sociaux connectés.
  • get /providersLes règles de chaque réseau : formats, emplacements et limites.

Publications

  • get /postsLes publications, filtrées par statut, dates, compte, réseau ou campagne.
  • post /postsCréer un brouillon de publication pour un ou plusieurs comptes.
  • get /posts/{id}Une publication avec ses comptes, sa vérification et ses médias.
  • patch /posts/{id}Modifier une publication. Envoyez la version que vous avez lue ; si elle a changé depuis, la réponse est 409.
  • delete /posts/{id}Supprimer une publication.
  • post /posts/{id}/publishPublier maintenant. La réponse est 202 : suivez la publication, ou un webhook, pour connaître le résultat.
  • post /posts/{id}/scheduleLa programmer à une heure donnée, avec un fuseau horaire.
  • post /posts/{id}/queueL’ajouter au prochain créneau libre d’une file d’attente.
  • post /posts/{id}/reviewL’envoyer en relecture avec une heure ou une file d’attente ; elle part une fois approuvée.
  • post /posts/{id}/retryRéessayer un compte qui a échoué.

Médias

  • get /mediaLa médiathèque, avec recherche et filtres.
  • post /media/uploadsDémarrer un import : la réponse indique où envoyer le fichier.
  • post /media/uploads/{id}/completeTerminer un import. Le fichier est ensuite vérifié et traité.
  • get /media/{id}Un fichier, avec son statut et ce que l’on sait de lui.
  • delete /media/{id}Supprimer un fichier. Un fichier encore utilisé par une publication répond 409.
  • put /media/{id}/alt-textEnregistrer ou effacer le texte alternatif d’un fichier.
  • post /media/{id}/alt-text/suggestionSuggérer un texte alternatif avec l’IA, sans l’enregistrer.

Statistiques

  • get /analyticsLes résultats pour une période.
  • get /analytics/exportLes mêmes résultats sous forme de fichier CSV.

Files d’attente

  • get /queuesLes files d’attente de publication.
  • post /queuesCréer une file d’attente avec ses créneaux hebdomadaires.
  • patch /queues/{id}Modifier une file d’attente.
  • delete /queues/{id}Supprimer une file d’attente.

Webhooks

  • get /webhooksLes endpoints de webhook.
  • post /webhooksAjouter un endpoint. La réponse contient son secret, cette fois seulement.

IA

  • get /aiSi l’IA est disponible, les crédits restants et le coût de chaque action.
  • post /ai/captionsSuggérer des reformulations de légende, des traductions ou des hashtags, sans les enregistrer.
  • post /ai/imagesGénérer une image. Interrogez GET /media/{id} jusqu’à ce qu’elle soit prête.