> ## Documentation Index > Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt > Use this file to discover all available pages before exploring further. # Entités > Référence des objets partagés et des champs d’indicateurs renvoyés par l’API v1. 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. ```json theme={null} { "success": true, "pagination": { "total": 156, "count": 10, "limit": 10, "offset": 0 }, "data": [ ... ] } ``` Nombre total d’éléments correspondant à la requête (toutes pages confondues) Nombre d’éléments renvoyés dans cette réponse Nombre maximal d’éléments par page (demandé ou par défaut) 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 : ```bash theme={null} GET /api/v1/brands/{brandId}/prompts?limit=20&offset=20 ``` Exemple de réponse : ```json theme={null} { "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. Lister les marques, obtenir le détail d’une marque Exemple fictif : ```json theme={null} { "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 } } ``` Identifiant opaque de la marque Nom affiché de la marque Domaine principal associé à la marque Description facultative de la marque (peut être null) Horodatage ISO 8601 de création de la marque Nombre total de prompts suivis pour cette marque Nombre total de réponses enregistrées pour cette marque 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. Lister les audits de prospection, obtenir un audit, obtenir le rapport d’un sujet Exemple fictif : ```json theme={null} { "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" } ] } ``` Sujet représenté par le rapport actuel. Le prospect d’origine utilise `self` ; les rapports dérivés utilisent un `subjectId` de concurrent stable. Tous les sujets qui peuvent être résolus dans cet audit. 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. Indique si la réponse contient le texte complet des réponses IA. Les réponses sont exclues par défaut. 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. Lister les concurrents, obtenir le détail d’un concurrent, évolution d’un concurrent Exemple fictif : ```json theme={null} { "id": "cmp_abc123", "name": "Rival Labs", "domain": "rival.example", "relationship": "DIRECT", "totalMentions": 111, "shareOfVoice": 8.73, "avgPosition": 2.3, "avgSentiment": 75.2 } ``` Identifiant unique du concurrent Nom affiché du concurrent Domaine principal du concurrent 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. 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. Position moyenne dans les listes lorsqu’il est mentionné (1 = premier, plus c’est bas, mieux c’est) 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. Domaines sources, URL sources, évolution des sources Exemple fictif : ```json theme={null} { "id": "src_xyz789", "domain": "publisher.example", "type": "MEDIA", "isSelf": false, "totalMentions": 102, "rate": 5.10, "avgPosition": 3.2, "aiSourceAuthorityScore": 61 } ``` Identifiant unique de la source Nom de domaine de la source 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 Indique si cette source appartient à votre marque Nombre total de citations dans les réponses IA **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. Position moyenne dans les listes de sources (1 = première) 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. Lister les prompts, obtenir le détail d’un prompt, réponses d’un prompt Exemple fictif : ```json theme={null} { "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" } ``` Identifiant unique du prompt Le texte du prompt ou de la question Nom du Topic ou mot-clé associé (peut être null) É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) Liste des noms de Tags pour l’organisation Personas actuellement rattachées au prompt, chacune avec `id`, `name` et `description` Identifiants des modèles actuellement configurés sur le prompt Indique si le suivi planifié est activé Fréquence de suivi effective : `NONE`, `DAILY`, `WEEKLY` ou `MONTHLY` (peut être null) Indique si la fréquence est héritée de la valeur par défaut de la marque Réponses demandées par modèle et par exécution Nombre de réponses IA générées pour ce prompt Réponses avec une mention SELF divisées par les réponses avec une mention SELF ou DIRECT, de 0 à 100 Réponses avec une citation SELF divisées par les réponses avec une citation SELF ou DIRECT, de 0 à 100 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. Lister les réponses, obtenir le détail d’une réponse Exemple fictif : ```json theme={null} { "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" } ``` Identifiant unique de la réponse Identifiant du prompt associé Texte du prompt associé Nom affiché du fournisseur Nom affiché du modèle Persona enregistrée lors de la génération de la réponse, avec `id`, `name` et `description` (peut être null) Texte complet de la réponse (ou aperçu dans les endpoints de liste) Indique si votre marque est mentionnée Position dans la liste des concurrents lorsqu’elle est mentionnée (null sinon) Indique si votre domaine est cité comme source Nombre de concurrents mentionnés dans cette réponse Nombre de sources citées dans cette réponse Score de sentiment de la mention SELF sur une échelle de 0 à 100, ou `null` 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 : ```json theme={null} { "name": "Acme Analytics", "position": 3, "relationship": "SELF", "sentiment": 85 } ``` Nom du concurrent tel que mentionné Position dans la réponse (1 = mentionné en premier) `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`. 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 : ```json theme={null} { "url": "https://publisher.example/article", "domain": "publisher.example", "position": 1, "isSelf": false } ``` URL complète citée (peut être null) Nom de domaine de la source Position dans la liste des sources (1 = citée en premier) Indique s’il s’agit de votre propre domaine *** ## Topic Un Topic (aussi appelé keyword) regroupe des prompts liés. Exemple fictif : ```json theme={null} { "id": "topic_abc123", "name": "Product Reviews" } ``` Identifiant unique du Topic Nom affiché du Topic *** ## Tag Les Tags permettent de classer les prompts selon vos propres catégories. Exemple fictif : ```json theme={null} { "id": "tag_xyz789", "name": "comparison" } ``` Identifiant unique du Tag Nom affiché du Tag *** ## Evolution data point Utilisé par les endpoints d’évolution pour suivre les indicateurs dans le temps. Exemple fictif : ```json theme={null} { "date": "2026-07-01", "mentions": 5, "shareOfVoice": 7.2, "avgPosition": 2.3, "avgSentiment": 76.5 } ``` Date au format YYYY-MM-DD Nombre de mentions à cette date Part de voix en pourcentage à cette date Position moyenne à cette date Sentiment moyen des mentions SELF à cette date, ou `null` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.