API REST v1 Lecture seule · JSON · Bearer token

Connectez les données Viscope à vos outils.

Réservée aux administrateurs et CDP, cette API permet de connecter les projets, indicateurs de visibilité IA, prompts, campagnes, réponses analysées et citations aux outils internes.

Les comptes utilisateurs, y compris bêta, n’ont pas accès à l’API. Les jetons externes historiques sont refusés.

Faire un premier appel

https://api.viscope.fr/api/v1

Démarrage rapide

Votre premier appel en trois étapes

Un administrateur ou un CDP crée son jeton depuis l’espace API, le conserve dans un gestionnaire de secrets, puis l’envoie dans l’en-tête Authorization.

1
Créer un accès interne

Un administrateur ou un CDP génère un jeton associé à son compte.
2
Conserver le jeton

Enregistrez le secret vcp_… côté serveur, jamais dans le navigateur ou Git.
3
Lire les projets

Appelez la collection avec le jeton Bearer interne.

Lister mes projets

curl 'https://api.viscope.fr/api/v1/client/projects?per_page=25' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <VOTRE_JETON>'

Authentification

Utiliser le jeton transmis

Seuls les administrateurs et CDP reçoivent un jeton, avec le scope client:read selon le besoin. Les comptes utilisateurs, y compris bêta, et leurs jetons historiques sont refusés. La gestion des autres jetons exige le scope séparé tokens:manage.

En-tête à envoyer sur chaque appel

Authorization: Bearer <VOTRE_JETON>

À la réception du jeton

Placez-le immédiatement dans votre gestionnaire de secrets. Ne l’ajoutez jamais à une URL, un fichier versionné, une application frontend ou un journal.

GET /auth/me

Vérifier le compte et les permissions du jeton.

GET /auth/tokens

Lister les jetons du compte avec tokens:manage.

DELETE /auth/tokens/{token}

Révoquer un jeton du compte avec tokens:manage.

Projets

Lire votre portefeuille et vos KPI

Un compte ne voit que les projets qui lui appartiennent ou lui ont été partagés. Un identifiant inaccessible ne révèle aucune donnée.

GET /client/projects

Lister les projets

Retourne les projets appartenant au compte ou partagés avec lui.

Filtres : page, per_page (1 à 100), active (true ou false).

GET /client/projects/{project}

Lire un projet

Retourne l’identité de la marque, ses domaines, son marché, ses concurrents et son rythme de mesure.

Remplacez {project} par l’identifiant numérique obtenu dans la liste.

GET /client/projects/{project}/overview

Lire la vue d’ensemble

Retourne les KPI de visibilité, la part de voix, le sentiment, la position, les tendances, marques et sources.

Utilisez cet endpoint pour alimenter un tableau de bord ou un reporting consolidé.

Mesures et réponses

Descendre du reporting jusqu’à la preuve

Partez d’une campagne, ouvrez ses réponses puis exploitez l’analyse structurée et les citations qui expliquent les KPI.

GET /client/projects/{project}/prompts

Lister les prompts

Retourne les questions suivies, leur thème, leur source et leur état.

Filtres : page, per_page et active.

GET /client/projects/{project}/runs

Lister les campagnes

Retourne les campagnes mesurées avec leur statut, moteurs, dates et nombre de réponses.

Filtres : page, per_page et status (queued, running, done, failed).

GET /client/projects/{project}/runs/{run}

Lire une campagne

Retourne une campagne et toutes les réponses exploitables produites par les moteurs.

Chaque réponse contient son analyse et ses citations lorsqu’elles sont disponibles.

GET /client/projects/{project}/responses/{response}

Comprendre une réponse

Retourne le texte, le moteur, la latence, la mention de marque, la position, le sentiment et les sources.

Les données techniques fournisseurs et les coûts internes ne sont jamais exposés.

GET /client/projects/{project}/sentiment

Analyser le sentiment

Retourne la synthèse, les perceptions, situations, tendances et le panorama des concurrents suivis.

Les résultats proviennent des analyses déjà enregistrées : cet appel ne déclenche aucune dépense.

GET /client/projects/{project}/competitors

Comparer les concurrents

Retourne les concurrents suivis, leurs mentions, positions, sentiments et leur matrice comparative.

Lecture seule, limitée aux données visibles par le compte.

GET /client/projects/{project}/sources

Lire les sources

Retourne la distribution des domaines et des types de sources cités.

Les données techniques des fournisseurs et les coûts internes sont exclus.

GET /client/projects/{project}/citations

Lister les citations

Retourne les citations avec leur domaine, URL, extrait, prompt et réponse associés.

Filtres : page et per_page (100 maximum).

Exemple de réponse analysée

Les champs absents ou non calculés peuvent valoir null.

{
  "data": {
    "id": 8421,
    "run_id": 321,
    "engine_key": "chat-gpt",
    "engine": "ChatGPT",
    "content": "La réponse complète du moteur…",
    "latency_ms": 2840,
    "analysis": {
      "brand_mentioned": true,
      "brand_position": 2,
      "sentiment": 4.2,
      "mention_category": "recommended",
      "summary": "La marque est recommandée pour…",
      "positive_points": ["Expertise reconnue"],
      "negative_points": []
    },
    "citations": [
      {
        "position": 1,
        "title": "Guide comparatif",
        "domain": "exemple.fr",
        "url": "https://exemple.fr/guide"
      }
    ]
  }
}

Pagination

Parcourir les collections

Les listes acceptent page et per_page. La taille par défaut est 25 et le maximum 100.

{
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 64,
    "last_page": 3
  },
  "links": {
    "first": "...page=1",
    "last": "...page=3",
    "prev": null,
    "next": "...page=2"
  }
}

Erreurs

Des réponses prévisibles

Une erreur contient toujours un message. Un code error stable est ajouté lorsqu’il existe, et les validations détaillent leurs champs dans errors.

401

Jeton absent, invalide, expiré ou révoqué.

403

Scope insuffisant ou projet non visible.

404

Ressource absente ou non rattachée au projet demandé.

422

Paramètres ou payload invalides.

429

Limite de requêtes atteinte.

Limite générale : 120 appels par minute et par compte.

Sécurité et intégration

Ce que l’API protège pour vous

Accès isolé

Chaque requête applique les mêmes règles de visibilité que votre compte Viscope.

Secrets maîtrisés

Seule l’empreinte SHA-256 du jeton est stockée ; le secret brut reste chez vous.

Données filtrées

Les coûts internes, payloads fournisseurs et secrets de partage ne sont jamais sérialisés.

CORS fermé

Une intégration navigateur nécessite une origine approuvée. Le serveur à serveur fonctionne sans configuration CORS.

Besoin du contrat machine ?

Le fichier OpenAPI décrit les endpoints, paramètres, formats et erreurs pour Postman, Swagger, les générateurs de SDK et vos tests automatisés.

Télécharger le contrat client