Entités

Ces structures communes apparaissent dans les réponses de l’API v1. Les pages des endpoints restent la référence pour les champs renvoyés par une route donnée.

Pagination

La plupart des endpoints de liste renvoient un objet pagination. L’endpoint des marques renvoie total sans pagination.

{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 10,
    "limit": 10,
    "offset": 0
  },
  "data": [ ... ]
}

object

Afficher Objet pagination

number

Nombre total d’éléments correspondant à la requête (toutes pages confondues)

number

Nombre d’éléments renvoyés dans cette réponse

number

Nombre maximal d’éléments par page (demandé ou par défaut)

number

Nombre d’éléments ignorés (pour la pagination)

Exemple de pagination

Pour récupérer la page 2 avec 20 éléments par page :

GET /api/v1/brands/{brandId}/prompts?limit=20&offset=20

Exemple de réponse :

{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 20,
    "limit": 20,
    "offset": 20
  },
  "prompts": [ ... ]
}

Brand

Une marque représente l’entreprise ou le produit suivi par un workspace.

Endpoints associés

Lister les marques, obtenir le détail d’une marque

Exemple fictif :

{
  "id": "brand_01",
  "name": "Acme Analytics",
  "domain": "acme.example",
  "description": "Analytics software for operations teams.",
  "createdAt": "2026-07-15T10:30:00.000Z",
  "stats": {
    "promptsCount": 156,
    "answersCount": 312,
    "competitorsCount": 8
  }
}

string

Identifiant opaque de la marque

string

Nom affiché de la marque

string

Domaine principal associé à la marque

string

Description facultative de la marque (peut être null)

string

Horodatage ISO 8601 de création de la marque

object

Afficher Statistiques de la marque

number

Nombre total de prompts suivis pour cette marque

number

Nombre total de réponses enregistrées pour cette marque

number

Nombre de concurrents (SELF + DIRECT)

Pitch Audit

Un audit de prospection est une ressource de rapport en lecture seule, générée pour le prospect d’une agence. Une fois terminé, ses données forment un instantané. Les rapports concurrents et co-concurrents sont des vues par sujet dérivées du même audit, pas des audits distincts.

Endpoints associés

Lister les audits de prospection, obtenir un audit, obtenir le rapport d’un sujet

Exemple fictif :

{
  "id": "8a218180-6dd7-43c7-a481-f6a1cc72dfd8",
  "status": "COMPLETED",
  "reportSubject": {
    "id": "self",
    "name": "Prospect Brand",
    "isOriginalBrand": true
  },
  "availableSubjects": [
    { "id": "self", "name": "Prospect Brand", "isOriginalBrand": true },
    { "id": "rival.example", "name": "Rival Labs", "isOriginalBrand": false }
  ],
  "answersIncluded": false,
  "answerCount": 24,
  "coCompetitors": [
    {
      "subjectId": "rival.example",
      "name": "Rival Labs",
      "scores": { "geoScore": 64, "mentionRate": 50 },
      "reportUrl": "/api/v1/pitch-audits/8a218180-6dd7-43c7-a481-f6a1cc72dfd8/reports/rival.example"
    }
  ]
}

object

Sujet représenté par le rapport actuel. Le prospect d’origine utilise self ; les rapports dérivés utilisent un subjectId de concurrent stable.

array

Tous les sujets qui peuvent être résolus dans cet audit.

array

Marques présentes dans les mêmes réponses que le sujet actuel. Utilisez le subjectId ou le reportUrl canonique de chaque ligne pour ouvrir son rapport dérivé. Avec includeCoCompetitorScores=true, chaque ligne inclut aussi sa synthèse scores complète.

boolean

Indique si la réponse contient le texte complet des réponses IA. Les réponses sont exclues par défaut.

number

Nombre de réponses disponibles, que leur texte ait été demandé ou non.

Competitor

Un concurrent est une marque ou un domaine détecté dans les réponses enregistrées et classé par rapport à la marque suivie.

Endpoints associés

Lister les concurrents, obtenir le détail d’un concurrent, évolution d’un concurrent

Exemple fictif :

{
  "id": "cmp_abc123",
  "name": "Rival Labs",
  "domain": "rival.example",
  "relationship": "DIRECT",
  "totalMentions": 111,
  "shareOfVoice": 8.73,
  "avgPosition": 2.3,
  "avgSentiment": 75.2
}

string

Identifiant unique du concurrent

string

Nom affiché du concurrent

string

Domaine principal du concurrent

string

Type de relation :

SELF : votre propre marque
DIRECT : concurrent direct (pris en compte dans le calcul de la part de voix)
INDIRECT : concurrent indirect (mentionné par l’IA sans être un rival direct)

L’endpoint de liste renvoie SELF et DIRECT par défaut et peut inclure INDIRECT via le filtre relationship. La part de voix des endpoints de détail et d’évolution utilise les mentions SELF et DIRECT. Sur l’endpoint de liste, la part de voix utilise les relations sélectionnées par le filtre.

number

Nombre total de mentions dans les réponses IA

Part de voix (0 à 100). Part de cette entité dans l’ensemble des mentions de marques des réponses IA : ses mentions divisées par le total des mentions SELF et DIRECT. Les mentions INDIRECT sont exclues.

number

Position moyenne dans les listes lorsqu’il est mentionné (1 = premier, plus c’est bas, mieux c’est)

number

Sentiment moyen des mentions sur une échelle de 0 à 100, ou null

Source

Une source est un domaine cité par les plateformes IA lorsqu’elles génèrent des réponses. Suivez les sites qui influencent les réponses IA dans votre secteur.

Endpoints associés

Domaines sources, URL sources, évolution des sources

Exemple fictif :

{
  "id": "src_xyz789",
  "domain": "publisher.example",
  "type": "MEDIA",
  "isSelf": false,
  "totalMentions": 102,
  "rate": 5.10,
  "avgPosition": 3.2,
  "aiSourceAuthorityScore": 61
}

string

Identifiant unique de la source

string

Nom de domaine de la source

string

Catégorie de la source :

INSTITUTIONAL : administrations, ONG, associations et organismes professionnels
COMMERCIAL : entreprises, boutiques en ligne, produits SaaS, agences et sites institutionnels d’entreprise
MEDIA : rédactions, journaux, magazines, diffuseurs et éditeurs à vocation journalistique
BLOG : blogs centrés sur des articles, qui ne sont ni des rédactions ni des références
SOCIAL : plateformes de profils, de fils d’actualité et de créateurs
FORUM : plateformes de discussion, de questions-réponses et communautés
EDUCATIONAL : écoles, universités, plateformes de cours et ressources pédagogiques
REFERENCE : documentation, wikis, encyclopédies, dictionnaires, normes, archives et bases de connaissances
OTHER : une vocation identifiée qui ne correspond à aucun des types ci-dessus

boolean

Indique si cette source appartient à votre marque

number

Nombre total de citations dans les réponses IA

number

Part des citations : pourcentage de l’ensemble des citations IA provenant de cette source (0 à 100). Par exemple, rate: 5.10 signifie que 5,10 % des citations renvoient à ce domaine.

number

Position moyenne dans les listes de sources (1 = première)

number | null

Dernier score public d’autorité de la source, ou null si aucun instantané suffisant n’est disponible

Prompt

Un prompt est une question suivie sur les fournisseurs IA. Chaque prompt peut avoir une étape du tunnel, un Topic et des Tags.

Endpoints associés

Lister les prompts, obtenir le détail d’un prompt, réponses d’un prompt

Exemple fictif :

{
  "id": "q_abc123",
  "text": "Which analytics platforms support warehouse exports?",
  "topic": "Data exports",
  "type": "TOFU",
  "tags": ["reviews", "comparison"],
  "personas": [{ "id": "persona_01", "name": "Data lead", "description": null }],
  "modelIds": ["openai-gpt-6.1-sol"],
  "monitoringEnabled": true,
  "frequency": "WEEKLY",
  "frequencyInherited": true,
  "boostCount": 1,
  "answersCount": 2,
  "mentionRate": 50.0,
  "sourceRate": 25.0,
  "lastGeneratedAt": "2026-07-19T10:00:00.000Z"
}

string

Identifiant unique du prompt

string

Le texte du prompt ou de la question

string

Nom du Topic ou mot-clé associé (peut être null)

string

Étape du tunnel marketing :

TOFU : haut du tunnel (découverte)
MOFU : milieu du tunnel (considération)
BOFU : bas du tunnel (décision)
POST_PURCHASE : après-achat (fidélisation et support)

array

Liste des noms de Tags pour l’organisation

array

Personas actuellement rattachées au prompt, chacune avec id, name et description

array

Identifiants des modèles actuellement configurés sur le prompt

boolean

Indique si le suivi planifié est activé

string

Fréquence de suivi effective : NONE, DAILY, WEEKLY ou MONTHLY (peut être null)

boolean

Indique si la fréquence est héritée de la valeur par défaut de la marque

number

Réponses demandées par modèle et par exécution

number

Nombre de réponses IA générées pour ce prompt

number

Réponses avec une mention SELF divisées par les réponses avec une mention SELF ou DIRECT, de 0 à 100

number

Réponses avec une citation SELF divisées par les réponses avec une citation SELF ou DIRECT, de 0 à 100

string

Horodatage ISO 8601 de la dernière génération de réponse

Answer

Une réponse est le résultat enregistré d’une exécution d’un fournisseur pour un prompt. Elle contient le texte, les mentions détectées et les citations.

Endpoints associés

Lister les réponses, obtenir le détail d’une réponse

Exemple fictif :

{
  "id": "ans_123abc",
  "promptId": "q_abc123",
  "promptText": "Which analytics platforms support warehouse exports?",
  "provider": "Example provider",
  "model": "example-model",
  "persona": null,
  "text": "Acme Analytics and Rival Labs both document warehouse exports...",
  "hasSelfMention": true,
  "selfMentionPosition": 3,
  "hasSelfSource": false,
  "competitorsCount": 5,
  "sourcesCount": 3,
  "sentiment": 82,
  "createdAt": "2026-07-19T10:00:00.000Z"
}

string

Identifiant unique de la réponse

string

Identifiant du prompt associé

string

Texte du prompt associé

string

Nom affiché du fournisseur

string

Nom affiché du modèle

object

Persona enregistrée lors de la génération de la réponse, avec id, name et description (peut être null)

string

Texte complet de la réponse (ou aperçu dans les endpoints de liste)

boolean

Indique si votre marque est mentionnée

number

Position dans la liste des concurrents lorsqu’elle est mentionnée (null sinon)

boolean

Indique si votre domaine est cité comme source

number

Nombre de concurrents mentionnés dans cette réponse

number

Nombre de sources citées dans cette réponse

number

Score de sentiment de la mention SELF sur une échelle de 0 à 100, ou null

string

Horodatage ISO 8601 de génération de la réponse

Competitor mention

Informations détaillées sur la mention d’un concurrent dans une réponse (renvoyées dans le détail des réponses). Exemple fictif :

{
  "name": "Acme Analytics",
  "position": 3,
  "relationship": "SELF",
  "sentiment": 85
}

string

Nom du concurrent tel que mentionné

number

Position dans la réponse (1 = mentionné en premier)

string

SELF, DIRECT ou INDIRECT. Le détail des réponses renvoie les mentions de tous les types de relation. Pour calculer la part de voix, ne gardez que les mentions SELF et DIRECT.

number

Score de sentiment de cette mention sur une échelle de 0 à 100, ou null

Source citation

Informations détaillées sur la citation d’une source dans une réponse (renvoyées dans le détail des réponses). Exemple fictif :

{
  "url": "https://publisher.example/article",
  "domain": "publisher.example",
  "position": 1,
  "isSelf": false
}

string

URL complète citée (peut être null)

string

Nom de domaine de la source

number

Position dans la liste des sources (1 = citée en premier)

boolean

Indique s’il s’agit de votre propre domaine

Topic

Un Topic (aussi appelé keyword) regroupe des prompts liés. Exemple fictif :

{
  "id": "topic_abc123",
  "name": "Product Reviews"
}

string

Identifiant unique du Topic

string

Nom affiché du Topic

Tag

Les Tags permettent de classer les prompts selon vos propres catégories. Exemple fictif :

{
  "id": "tag_xyz789",
  "name": "comparison"
}

string

Identifiant unique du Tag

string

Nom affiché du Tag

Evolution data point

Utilisé par les endpoints d’évolution pour suivre les indicateurs dans le temps. Exemple fictif :

{
  "date": "2026-07-01",
  "mentions": 5,
  "shareOfVoice": 7.2,
  "avgPosition": 2.3,
  "avgSentiment": 76.5
}

string

Date au format YYYY-MM-DD

number

Nombre de mentions à cette date

Part de voix en pourcentage à cette date

number

Position moyenne à cette date

number

Sentiment moyen des mentions SELF à cette date, ou null

Bien démarrer

Configurer les données

Suivi et mesure

Analyse et action

Agence et automatisation

Guides d’implémentation

Brand

Endpoints associés

Pitch Audit

Endpoints associés

Competitor

Endpoints associés

Source

Endpoints associés

Prompt

Endpoints associés

Answer

Endpoints associés

Competitor mention

Source citation

Topic

Tag

Evolution data point

​Pagination

​Exemple de pagination

​Brand

Endpoints associés

​Pitch Audit

Endpoints associés

​Competitor

Endpoints associés

​Source

Endpoints associés

​Prompt

Endpoints associés

​Answer

Endpoints associés

​Competitor mention

​Source citation

​Topic

​Tag

​Evolution data point

Pagination

Exemple de pagination

Brand

Pitch Audit

Competitor

Source

Prompt

Answer

Competitor mention

Source citation

Topic

Tag

Evolution data point