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
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
Listez vos comptes sociaux :
Terminal curl https://app.spreva.ai/api/v1/social-accounts \ -H "Authorization: Bearer spreva_sk_..." - 3
Lisez la réponse. Les résultats se trouvent dans
data, et l’idd’un compte est ce que vous passez commeconnectionIdquand 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é.
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
429dont le message indique combien de secondes attendre. - Les erreurs sont renvoyées dans la langue de l’en-tête
Accept-Languagede la requête ; leurcodene change jamais. - Depuis un navigateur connecté à SPREVA, envoyez
x-workspace-idavec 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
clippers:read- Voir votre programme de clippeurs, ses comptes et leurs chiffres
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
clippers:write- Configurer les clippeurs et approuver, refuser ou retirer des comptes
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.
{
"error": {
"code": "FORBIDDEN",
"message": "API key needs the posts:write scope for posts:create"
}
}- 400
INVALID_REQUEST, INVALID_JSON, WORKSPACE_REQUIREDLe 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
UNAUTHENTICATEDLa clé est absente, mal saisie, révoquée ou expirée. Envoyez « Authorization: Bearer <key> ».
- 402
ENTITLEMENT_EXCEEDED, AI_LIMIT_REACHED, CLIPPER_LIMIT_REACHEDL’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
FORBIDDENLa 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_FOUNDAucun 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, CLIPPER_PROGRAM_CLOSED, CLIPPER_ACCOUNT_ELSEWHERELa 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, CLIPPER_RULE_NEEDS_WORDS, CLIPPER_NETWORK_NOT_ALLOWED, CLIPPER_NAME_RULELe 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_BUSYPlus 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
INTERNALUne 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_UNAVAILABLELe 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 :
https://app.spreva.ai/api/openapi.jsonComptes 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 laversionque vous avez lue ; si elle a changé depuis, la réponse est409.delete /posts/{id}Supprimer une publication.post /posts/{id}/publishPublier maintenant. La réponse est202: 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épond409.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.post /posts/{id}/metrics/refreshLit tout de suite les chiffres d’une publication sur chaque réseau où elle est sortie.429avecRetry-Aftertant que la dernière actualisation date de moins de cinq minutes.post /social-accounts/{id}/metrics/refreshLit tout de suite les abonnés d’un compte. La même attente de cinq minutes qu’une publication.
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. InterrogezGET /media/{id}jusqu’à ce qu’elle soit prête.
Clippeurs
get /clippersLes comptes associés à votre programme de clippeurs, avec leurs vues sur une période.get /clippers/statsLes vues de vos clippeurs sur une période : le total, par réseau, par jour et, si vous le demandez, par compte.get /clippers/calendarCe que vos clippeurs ont programmé dans SPREVA sur une période, et ce qui est sorti ainsi, du plus proche au plus lointain.get /clippers/exportTous les comptes que votre programme a eus, avec leurs vues sur une période, dans un fichier CSV.get /clippers/{id}Un compte associé, avec ses vues sur une période.get /clippers/{id}/postsSes publications depuis son association, de la plus récente à la plus ancienne, avec les vues que le réseau indique.post /clippers/{id}/approveApprouver un compte en attente. Ses publications comptent à partir de maintenant.post /clippers/{id}/declineRefuser un compte en attente, avec un motif que le clippeur lit si vous en donnez un.post /clippers/{id}/removeRetirer un compte, avec un motif que le clippeur lit si vous en donnez un. Ce qu’il a apporté reste dans vos totaux.get /clippers/programVotre programme : son lien, sa règle de nom et la façon dont les comptes sont approuvés.post /clippers/programConfigurer votre programme et obtenir le lien que vous partagez avec les clippeurs.patch /clippers/programModifier le programme, cesser d’accepter de nouveaux comptes, le mettre en pause ou le fermer. La fermeture met fin à toutes les associations.