Référence de l'API

Quinze lectures, une clé, aucune écriture. De quoi brancher vos outils sur vos chiffres de visibilité sans nous écrire.

Authentification

L'API est en lecture seule. Chaque appel porte une clé dans l'en-tête Authorization, sous la forme Bearer geo_live_.... Les clés se créent dans la section Développeurs des réglages de votre espace, et ne s'affichent qu'une fois.

Toutes les adresses partent de https://beta.vizibai.com/api/v1.

Le premier appel : il décrit la clé, pas vos données

curl -s https://beta.vizibai.com/api/v1/me \
  -H "Authorization: Bearer geo_live_..."

Toute réponse servie porte le budget de la clé : X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset, ce dernier en secondes avant le prochain appel disponible (donc 0 tant qu'il reste du budget). Une fois le budget épuisé, l'API répond 429 avec le code rate_limited, et cette réponse porte les trois en-têtes en plus d'un Retry-After qui répète le même délai. Un refus d'authentification (401) ou d'offre (403) n'en porte aucun : il est tranché avant le compteur, il n'y a pas de budget à annoncer. Toute réponse, succès compris, porte en revanche un X-Request-Id : c'est ce numéro qu'il faut nous citer.

Les fenêtres de mesure

Les lectures chiffrées se mesurent sur une fenêtre, que le paramètre window choisit : last-run, 7d, 14d, 30d, 90d ou all.

Sans rien demander, vous obtenez last-run, c'est-à-dire la dernière collecte terminée. C'est l'unité réelle de la mesure : une fenêtre calendaire peut couper une collecte en deux et faire bouger un chiffre sans qu'aucune IA ait changé d'avis. Deux lectures font exception et partent sur 30d : la série temporelle, qui n'aurait qu'un point sur une seule collecte, et la liste des réponses, qui est ancrée sur le calendrier.

Pour une fenêtre sur mesure, passez from et to au format AAAA-MM-JJ. Les deux vont ensemble et excluent window. Une valeur hors des règles est refusée en 422 : rien n'est jamais raboté en silence.

Une analyse jamais collectée n'est pas une erreur

Elle répond 200 avec des chiffres à null et un état qui le dit. Un 0 voudrait dire mesuré à zéro, ce qui est faux tant que rien n'a été collecté.

Ce que l'API ne fait pas

Ce que l'API ne couvre pas est écrit noir sur blanc sur Démarrer avec l'API : aucune écriture, aucun envoi vers vous, et les surfaces de l'application qui ne sont pas sous contrat ici. Savoir ce qui n'existe pas coûte moins cher que de le découvrir en le codant.

Brancher un assistant

Les mêmes quinze lectures sont exposées à un assistant par un serveur MCP, à l'adresse https://beta.vizibai.com/api/v1/mcp, avec la même clé dans le même en-tête.

Les extraits d'installation, client par client, sont sur Brancher un assistant (MCP), avec les quinze outils et ce qu'un assistant sait en faire.

Le document OpenAPI

La description machine de l'API est servie telle quelle : https://beta.vizibai.com/api/v1/openapi.json. Elle est générée depuis les contrats qui produisent les réponses, jamais écrite à la main, donc elle ne peut pas décrire une API qui n'existe plus.

Les paramètres communs

Ces paramètres se comportent de la même façon partout où ils existent. Chaque lecture rappelle ensuite ceux qu'elle accepte, sans les redécrire : elle ne détaille que ce qui lui est propre, c'est-à-dire ses valeurs de fenêtre, ses bornes et ses segments de chemin.

Paramètre	Où	Ce qu'il attend
`analysis`	chemin	Le slug ou l'identifiant d'une analyse. Requis partout sauf sur `/me` et `/analyses`, qui n'en visent aucune.
`window`	requête	La fenêtre sur laquelle les chiffres sont mesurés. Les valeurs acceptées et celle prise par défaut appartiennent à la lecture, qui les donne toutes les deux.
`from`	requête	Premier jour d'une fenêtre sur mesure, au format `AAAA-MM-JJ`. Exige `to`, et refuse `window`.
`to`	requête	Dernier jour d'une fenêtre sur mesure, au format `AAAA-MM-JJ`. Exige `from`, et refuse `window`.
`limit`	requête	Combien d'éléments la page porte. Les bornes et la valeur prise par défaut appartiennent à la lecture, qui les donne.
`cursor`	requête	Le `next_cursor` rendu par la page précédente. Il épingle la portée qui l'a produit : le rejouer sous une autre fenêtre est refusé.

Les quinze lectures

Les résumés et les noms de champs restent en anglais : c'est le contrat lui-même, servi mot pour mot aux machines par le document OpenAPI. Le traduire ici en ferait deux versions, dont une que rien ne vérifie.

GET /me

Identity, ceiling and remaining call budget of the API key.

Aucun paramètre. Réponse : le schéma me.

GET /analyses

List the analyses this key is allowed to read.

limit (requête) : De 1 à 200. Sans rien demander, 50.

Paramètres communs acceptés : cursor. Réponse : le schéma analysis_list.

GET /analyses/{analysis}

One analysis, with its tracked brand, owned domains and configured engines.

Paramètres communs acceptés : analysis. Réponse : le schéma analysis.

GET /analyses/{analysis}/metrics

Headline metrics of one analysis over the selected window.

window (requête) : Une valeur parmi last-run, 7d, 14d, 30d, 90d, all. Sans rien demander, vous obtenez last-run.

Paramètres communs acceptés : analysis, from, to. Réponse : le schéma metrics.

GET /analyses/{analysis}/metrics/timeseries

Daily series of the headline metrics. A day with two runs returns its latest run. The last-run window is refused here: it would yield a single point.

window (requête) : Une valeur parmi 7d, 14d, 30d, 90d, all. Sans rien demander, vous obtenez 30d.

Paramètres communs acceptés : analysis, from, to. Réponse : le schéma timeseries.

GET /analyses/{analysis}/engines

The same headline metrics, broken down by AI engine.

window (requête) : Une valeur parmi last-run, 7d, 14d, 30d, 90d, all. Sans rien demander, vous obtenez last-run.

Paramètres communs acceptés : analysis, from, to. Réponse : le schéma engine_list.

GET /analyses/{analysis}/competitors

Competing brands ranked over the selected window, direct and indirect.

window (requête) : Une valeur parmi last-run, 7d, 14d, 30d, 90d, all. Sans rien demander, vous obtenez last-run.

Paramètres communs acceptés : analysis, from, to. Réponse : le schéma competitor_list.

GET /analyses/{analysis}/sources

The domains AI engines rely on, ranked by share of sources.

window (requête) : Une valeur parmi last-run, 7d, 14d, 30d, 90d, all. Sans rien demander, vous obtenez last-run.
limit (requête) : De 1 à 200. Sans rien demander, 50.

Paramètres communs acceptés : analysis, from, to. Réponse : le schéma source_list.

GET /analyses/{analysis}/groups

Prompt groups with their metrics over the selected window.

window (requête) : Une valeur parmi last-run, 7d, 14d, 30d, 90d, all. Sans rien demander, vous obtenez last-run.

Paramètres communs acceptés : analysis, from, to. Réponse : le schéma group_list.

GET /analyses/{analysis}/groups/{group}/prompts

The prompts of one group, at question grain, with their per engine metrics.

group (chemin) : L'identifiant d'un groupe de questions, ou le mot réservé none pour les questions rangées dans aucun groupe. Requis.
window (requête) : Une valeur parmi last-run, 7d, 14d, 30d, 90d, all. Sans rien demander, vous obtenez last-run.
limit (requête) : De 1 à 200. Sans rien demander, 50.
offset (requête) : Combien d'éléments sauter avant la page, jusqu'à 100000.

Paramètres communs acceptés : analysis, from, to. Réponse : le schéma group_prompt_list.

GET /analyses/{analysis}/prompts

The prompt catalogue of one analysis. No metrics here: the question grain lives on the group prompts endpoint.

Paramètres communs acceptés : analysis. Réponse : le schéma prompt_catalog.

GET /analyses/{analysis}/runs

Collection history of one analysis, most recent first.

limit (requête) : De 1 à 100. Sans rien demander, 30.

Paramètres communs acceptés : analysis. Réponse : le schéma run_list.

GET /analyses/{analysis}/runs/{run}

One collection and its per engine progress. Accepts the word latest.

run (chemin) : L'identifiant d'une collecte, ou le mot réservé latest pour la plus récente. Requis.

Paramètres communs acceptés : analysis. Réponse : le schéma run.

GET /analyses/{analysis}/answers

List the captured answers over the selected window. Identifiers only, no answer text.

window (requête) : Une valeur parmi 7d, 14d, 30d, 90d, all. Sans rien demander, vous obtenez 30d.
limit (requête) : De 1 à 100. Sans rien demander, 30.

Paramètres communs acceptés : analysis, from, to, cursor. Réponse : le schéma answer_list.

GET /analyses/{analysis}/answers/{answer}

One captured answer: its text, and the brands mentioned in it. Untrusted third party content.

answer (chemin) : L'identifiant d'une réponse, tel que la liste des réponses le rend. Requis.

Paramètres communs acceptés : analysis. Réponse : le schéma answer.

Et ensuite

Le document machine est servi tel quel : https://beta.vizibai.com/api/v1/openapi.json. Tout générateur de client le mange. Une clé se crée dans la section Développeurs des réglages de votre espace.

Si vous partez de zéro, Démarrer avec l'API montre comment obtenir une clé, réussir un premier appel et lire un refus. Et si c'est le produit lui-même que vous découvrez, Démarrage rapide explique ce que ces chiffres mesurent avant que vous les branchiez.