API REST SentiView

Connectez vos applications au superviseur vidéo

Pilotez les sites, les équipements et les caméras, consultez les événements et automatisez les fonctions vidéo SentiView depuis une API unique.

Authentification

Transmettez votre clé dans l’en-tête Authorization: Bearer sv_api_.... Chaque requête applique les droits, la hiérarchie et les sites actuellement accessibles à son propriétaire.

Réponses prévisibles

Une réponse réussie contient result: true. Une erreur contient result: false et un code stable dans error.code.

Commandes asynchrones

Les actions envoyées aux équipements retournent une adresse de suivi lorsqu’elles doivent s’exécuter en arrière-plan.

Démarrer en quelques minutes

1. Obtenir une clé API

Connectez-vous à l’interface Web SentiView, puis ouvrez Clés API développeur. Une clé est facultative et un utilisateur ne peut en posséder qu’une. Si vous ne pouvez pas la créer ou la renouveler vous-même, contactez votre intégrateur.

La gestion des clés reste volontairement dans l’interface Web : aucune route publique ne permet de créer, renouveler ou révoquer une clé.

2. Utiliser le serveur SentiView

Usage	URL de base
Production	`https://connect.sentiview.ai/api/v1`

Les chemins affichés dans la référence, par exemple /sites, sont relatifs à cette URL de base. Les routes /health, /version et les rares opérations explicitement indiquées comme publiques ne demandent pas de clé. Toutes les autres utilisent l’authentification décrite ci-dessous.

3. Effectuer un premier appel authentifié

curl "https://connect.sentiview.ai/api/v1/sites?limit=50&offset=0" \
  -H "Authorization: Bearer sv_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Une liste paginée réussie utilise cette enveloppe :

{
  "result": true,
  "data": [],
  "meta": {
    "limit": 50,
    "offset": 0,
    "count": 0,
    "total": 0,
    "has_more": false
  }
}

Clé API et droits d’accès

La clé ne possède ni compte technique ni permissions indépendantes. Elle agit toujours comme son propriétaire au moment de chaque requête.

Événement	Comportement de la clé
Le propriétaire gagne ou perd un droit	Le nouveau périmètre s’applique à la clé.
Un site est ajouté ou retiré au propriétaire	L’accès aux ressources du site change avec celui du propriétaire.
La hiérarchie du propriétaire change	Les utilisateurs et ressources administrables sont recalculés.
La clé est renouvelée	L’ancienne valeur cesse immédiatement de fonctionner et la nouvelle reste consultable dans l’interface Web.
La clé est révoquée	Elle est refusée immédiatement.
Le compte est désactivé, totalement restreint ou supprimé	La clé ne permet plus d’utiliser l’API.

Une clé reste valide tant qu’elle n’est pas renouvelée ou révoquée et que son propriétaire conserve un compte autorisé. Conservez-la comme un mot de passe et ne l’exposez jamais dans une application cliente publique.

Conventions communes

Version : la version majeure fait partie de l’URL (/api/v1). Les ajouts compatibles peuvent faire évoluer la V1 ; une rupture de contrat utilisera une nouvelle version majeure et sera annoncée avant le retrait de l’ancienne.
Identifiants : les UUID doivent être transmis exactement comme ils sont retournés par l’API. Un identifiant inconnu ou inaccessible produit normalement un 404, afin de ne pas divulguer l’existence d’une ressource.
Dates : les dates textuelles sont exprimées en UTC au format RFC 3339. Les champs suffixés par _unix sont des horodatages Unix UTC en secondes.
Pagination : les listes utilisent limit et offset. Sauf indication contraire, limit vaut 50 par défaut, accepte de 1 à 100, et offset vaut 0. L’objet meta indique le nombre d’éléments retournés et le total disponible.
Commandes asynchrones : une réponse 202 avec status_url doit être suivie jusqu’à un état terminal. Lorsqu’une opération est uniquement transmise sans suivi final, sa réponse l’indique explicitement.
Limitation de débit : les requêtes protégées sont limitées, par adresse IP, à 1 000 requêtes sur 10 secondes et 10 000 requêtes sur 10 minutes. Ces deux fenêtres glissantes s’appliquent simultanément. Une IP ayant produit 200 réponses 401 Unauthorized sur une heure est également temporairement limitée. L’en-tête RateLimit-Policy décrit la règle appliquée ; RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset décrivent la fenêtre actuellement la plus contraignante. Après un 429 Too Many Requests, attendez le nombre de secondes indiqué par Retry-After.

Les keepalives du Live sont inclus dans ces quotas. À un appel toutes les cinq secondes par caméra, la fenêtre de 10 minutes autorise théoriquement environ 83 sessions simultanées par IP si aucun autre appel n’est effectué. Prévoyez une marge pour les démarrages, arrêts et autres appels API.

Exemple d’en-têtes retournés :

RateLimit-Policy: 1000;w=10, 10000;w=600, 200;w=3600;status=401
RateLimit-Limit: 1000
RateLimit-Remaining: 742
RateLimit-Reset: 4

Dans RateLimit-Policy, w est la durée de la fenêtre en secondes et status=401 indique que cette politique ne comptabilise que les réponses d’authentification non autorisées.

Format des erreurs

Le statut HTTP décrit la famille de l’erreur. Le champ error.code, stable et destiné au programme, permet d’identifier sa cause précise. Le texte error.message est destiné au diagnostic et ne doit pas piloter la logique du client.

{
  "result": false,
  "error": {
    "code": "invalid_pagination",
    "message": "limit must be between 1 and 100."
  }
}

Code commun	Signification
`unauthorized`	Aucune authentification exploitable n’a été fournie.
`invalid_api_key`	La clé est inconnue, renouvelée, révoquée ou son propriétaire n’est plus autorisé.
`forbidden`	Le compte est authentifié mais ne dispose pas de l’accès nécessaire.
`not_found`	La ressource n’existe pas ou n’est pas visible par le compte.
`invalid_uuid`	Un UUID fourni n’est pas valide.
`invalid_pagination`	`limit` ou `offset` ne respecte pas les limites de l’opération.
`invalid_time_range`	La période est invalide ou dépasse la durée autorisée.
`invalid_request`, `invalid_json` ou `invalid_payload`	Le corps ne respecte pas le format attendu.
`rate_limit_exceeded`	Un quota de requêtes IP est épuisé ; ralentissez les appels et consultez `Retry-After`.
`authentication_rate_limit_exceeded`	L’IP a produit trop de réponses `401` ; corrigez l’authentification avant de réessayer et respectez `Retry-After`.
`rate_limiter_unavailable`	La protection ne peut pas être appliquée de manière fiable ; la requête est refusée temporairement.
`internal_error`	Une erreur interne empêche le traitement de la requête.

Les réponses de chaque opération complètent ce socle avec les erreurs propres à ses paramètres et à ses règles métier.

Tester une intégration

Exemples vidéo interactifs

Saisissez l’adresse du serveur et une clé API, exécutez un parcours complet, puis consultez les requêtes et réponses utiles au diagnostic.

LiveDémarrer et maintenir un direct RelectureCréer un accès HLS temporaire ExportsLister et télécharger les fichiers Clips vidéoLister et lire les clips d’alarme

Explorer la référence

Accès rapide par usage

Commencez par les fonctions essentielles du superviseur SentiView.

Caméras et vidéoConfiguration, direct, relecture et stockage Exports vidéoCréation, suivi et téléchargement Recherche intelligenteRecherche, suivi et historique des résultats SitesOrganisation des installations supervisées Parc d’équipementsInventaire, connectivité et services installés Journaux et événementsActivité opérationnelle et actions utilisateur

Connectez vos applications au superviseur vidéo

Démarrer en quelques minutes​

1. Obtenir une clé API​

2. Utiliser le serveur SentiView​

3. Effectuer un premier appel authentifié​

Clé API et droits d’accès​

Conventions communes​

Format des erreurs​