Projets
Un projet correspond à une marque suivie : son domaine, son pays et sa langue, ses prompts et ses concurrents. Presque tous les autres endpoints demandent un project_id : commencez donc par ici.
GET/dimensions/projects
Liste les projets de l’utilisateur authentifié (permet aussi de tester l’authentification). Les projets de pitch, des instantanés ponctuels supprimés 90 jours après leur création, sont exclus, sauf avec pitch=include ou pitch=only.
GET/dimensions/projects/:id
Renvoie le détail d’un projet : variantes du nom, domaines propriétaires supplémentaires, secteur d’activité, modèle économique, nombre de prompts selon la marque dans le prompt, limite de prompts propre au projet (prompt_limit, null s’il n’en a pas) avec stats.prompts_available (nombre de prompts encore ajoutables : la plus petite valeur entre la marge restante du projet sous cette limite et les prompts restants du compte, null si aucune des deux ne s’applique), et data_coverage (les modèles, pays et langues qui ont réellement des données). Un seul appel remplace ainsi les appels distincts aux endpoints models et locales.
GET/dimensions/models
Liste les modèles présents dans les métriques quotidiennes du projet.
GET/dimensions/locales
Liste les pays et les langues présents dans les métriques quotidiennes du projet.
POST/projects
Crée un projet complet en un seul appel (mode rapide) : le projet, les prompts (mis en file d’attente pour exécution et catégorisation), les concurrents et l’abonnement à l’e-mail hebdomadaire. Idempotent lorsque external_identifier est fourni. Le projet appartient toujours au propriétaire du compte.
- Corps (JSON) :
website_url(obligatoire, URL HTTP(S) publique avec un nom d’hôte DNS ou une adresse IP publique ; les identifiants de connexion, les adresses IP privées et spéciales, localhost et les noms d’hôte internes sont refusés),name(obligatoire),main_country(obligatoire),main_language(obligatoire),brand_name,description,industry(une clé ou un tableau ; une clé inconnue est refusée avec la liste des clés valides),business_model,target_audience,brand_voice,goals,primary_products(tableau),matching_names(tableau),prompts(tableau, 100 au maximum),collections(tableau de {name, prompts}, 50 au maximum, chacun attribuant un tag aux prompts de la même requête d’après leur texte exact),competitors(tableau de {domain, brand_name, matching_names}),owned_media(objet, à partir de Growth),use_subdomain,weekly_email_subscribed,external_identifier(comptes avec intégration iframe uniquement ; clé d’idempotence, [a-z0-9_-]{1,64}),execute_prompts_immediately(true par défaut),pitch(false par défaut ; true crée un projet de pitch, un instantané ponctuel pour un prospect, exécuté une seule fois, qui n’occupe aucun emplacement de projet et est supprimé au bout de 90 jours s’il n’est pas converti ; il consomme l’un des projets de pitch du mois et accepte de 1 à 100 prompts).
PATCH/projects/:id
Met à jour le profil du projet (le Brand book et la détection de la marque), les mêmes champs que dans Paramètres du projet, les autres domaines de la marque et la limite de prompts du projet. Les sept champs du Brand book (industry, business_model, description, primary_products, target_audience, brand_voice, goals) alimentent chaque tâche GEO Writer et les suggestions de prompts. industry, description et target_audience aident aussi les recommandations à ajuster leurs conseils. Modifier matching_names relance en arrière-plan la détection des mentions et des citations sur tout l’historique du projet, et modifier additional_owned_domains retraite les réponses passées qui citent un domaine ajouté ou retiré (rematching: true, modifications bloquées pendant ce temps) ; un changement de brand_name ne s’applique qu’aux exécutions futures. Seul le propriétaire du compte peut modifier additional_owned_domains. prompt_limit fonctionne comme dans Paramètres du compte > Limites de prompts (une limite inférieure ne supprime aucun prompt), et une requête qui n’envoie que ce champ est enregistrée même pendant un recalcul. pitch: false, envoyé seul, convertit un projet de pitch en projet suivi : il conserve ses données, occupe un emplacement de projet, ses prompts s’exécutent à la fréquence de suivi du compte, et la conversion est irréversible. Les champs inconnus sont refusés, et une requête est appliquée entièrement ou pas du tout.
- Corps (JSON), avec uniquement les champs à modifier :
name(un libellé ; il ne modifie la détection des mentions que sibrand_nameest vide),brand_name,description,industry(une clé, ou un tableau enregistré tel quel),business_model,target_audience,brand_voice,goals,primary_products(tableau de remplacement complet),matching_names(tableau de remplacement COMPLET ; envoyez toutes les variantes à conserver),additional_owned_domains(tableau de remplacement COMPLET de 10 domaines au maximum, chacun étant le domaine propre d’un site : les sous-domaines et les plateformes partagées par de nombreuses entreprises sont donc refusés ;[]vide la liste ; propriétaire du compte uniquement),prompt_limit(le nombre maximal de prompts du projet, comme dans Paramètres du compte > Limites de prompts : un nombre entier de 1 à 2147483647, ounullpour supprimer la limite ; réservé au propriétaire du compte ou à un admin du compte (copropriétaire) disposant de l’autorisation de modifier les projets ; une clé limitée à certains projets reçoitERR_KEY_PROJECT_SCOPED).
DELETE/projects/:id
Supprime un projet, comme « Supprimer le projet » dans Paramètres du projet. Cette action est irréversible : le projet disparaît immédiatement et libère un emplacement de projet, puis une tâche en arrière-plan supprime ses prompts, réponses, mentions, citations, données de sentiment, concurrents et l’historique de ses métriques. Les clés API limitées au projet n’y ont plus accès, et une clé qui ne garde aucun projet est révoquée. Un membre de l’équipe doit disposer de l’autorisation de supprimer des projets.
:ididentifiant du projet
Un projet auquel la clé n’a pas accès, ou déjà en cours de suppression, renvoie ERR_PROJECT_NOT_FOUND. Nécessite une clé read_write qui n’est pas limitée à certains projets (sinon ERR_KEY_PROJECT_SCOPED).
Assistant de création de projet
Assistant de création de projet en plusieurs étapes, avec suggestions de l’IA : POST /project_drafts lance un brouillon (et renvoie un nom, une description et un secteur d’activité suggérés pour l’URL), PATCH envoie chaque étape (details, prompts, competitors, owned_media) avec une progression strictement séquentielle et renvoie des suggestions pour l’étape suivante, POST /project_drafts/:id/finalize crée le projet définitif. Les brouillons expirent au bout de 24 h.
- La valeur initiale de
website_urldoit être une URL HTTP(S) publique avec un nom d’hôte DNS ou une adresse IP publique. Les identifiants de connexion, les adresses IP privées et spéciales, localhost et les noms d’hôte internes sont refusés. Étapes :details(nom obligatoire),prompts(100 au maximum, vérifiés par rapport au quota),competitors(plafonnés selon le forfait),owned_media(facultatif, à partir de Growth). Chaque étape propose des suggestions, désactivables avecsuggest=false; pour une URL jamais analysée, elles peuvent prendre jusqu’à 2 minutes environ : réglez le délai d’expiration du client sur 180 s. La finalisation est idempotente et revalide tous les contrôles.