Référence API

Présentation

L'API CoreSight est une API REST exposée sur HTTPS. Toutes les réponses sont au format JSON.

Base URL : https://votre-serveur (ou https://votre-domaine.com)

Authentification

Toutes les routes API (sauf les routes publiques) nécessitent un token d'authentification transmis dans le header Authorization :

Authorization: Bearer <token>

Obtenir un token (connexion)

curl -X POST https://votre-serveur/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@coresight.io", "password": "votre-mdp"}'

Réponse :

{
  "token": "abc123...",
  "user": {
    "id": "1",
    "email": "admin@coresight.io",
    "name": "Admin",
    "role": "admin"
  }
}

Clés API (ingestion automatisée)

Pour les intégrations automatisées, utilisez des clés API (sans expiration) plutôt que des tokens de session.

Créez une clé depuis Mon Compte → Clés API → Générer.

# Exemple avec clé API
curl -X POST https://votre-serveur/api/integrations/ingest \
  -H "Authorization: Bearer <votre-clé-api>" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

Endpoint de santé (public)

GET /api/health

Réponse :

{
  "status": "ok",
  "message": "CoreSight backend en ligne",
  "version": "1.1.0",
  "uptime": 3600
}

---

Actifs

Lister les actifs

GET /api/assets

Paramètres de requête :

Paramètre	Type	Description
limit	entier	Nombre de résultats (défaut: 100)
offset	entier	Décalage pour la pagination
search	chaîne	Recherche textuelle
type	chaîne	Filtrer par type

Réponse :

{
  "assets": [
    {
      "id": "asset-001",
      "name": "Switch-Core-01",
      "ip": "10.0.1.1",
      "type": "switch",
      "vendor": "Cisco",
      "risk_score": 3,
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "total": 142
}

Créer un actif

POST /api/assets
Content-Type: application/json

{
  "name": "Switch-Core-01",
  "ip": "10.0.1.1",
  "type": "switch",
  "vendor": "Cisco",
  "model": "Catalyst 9300",
  "risk_score": 3,
  "site": "Paris DC"
}

Modifier un actif

PUT /api/assets/:id
Content-Type: application/json

{ "risk_score": 7, "os_version": "IOS-XE 17.9" }

Supprimer un actif

DELETE /api/assets/:id

---

Ingestion (import en masse)

Ingérer des actifs et relations

POST /api/integrations/ingest
Authorization: Bearer <clé-api>
Content-Type: application/json

Corps :

{
  "assets": [
    {
      "id": "ext-001",
      "name": "Switch-Core-01",
      "ip": "10.0.1.1",
      "type": "switch",
      "vendor": "Cisco",
      "vulnerabilities": [
        {
          "id": "CVE-2024-1234",
          "score": 8.5,
          "summary": "Buffer overflow in...",
          "publishedDate": "2024-03-01"
        }
      ]
    }
  ],
  "relations": [
    {
      "sourceAssetId": "ext-001",
      "targetAssetId": "ext-002",
      "type": "connects",
      "direction": "bi"
    }
  ],
  "options": {
    "mode": "merge",
    "deleteStale": false
  }
}

Modes d'ingestion :

Mode	Description
merge	Met à jour les actifs existants (par id ou ip)
replace	Remplace tout l'inventaire
append	Ajoute sans vérifier les doublons

Réponse :

{
  "success": true,
  "stats": {
    "assetsCreated": 15,
    "assetsUpdated": 8,
    "relationsCreated": 12,
    "duration": "340ms"
  }
}

---

Relations

Lister les relations

GET /api/relations

Créer une relation

POST /api/relations
Content-Type: application/json

{
  "sourceAssetId": "asset-001",
  "targetAssetId": "asset-002",
  "type": "connects",
  "direction": "mono",
  "protocol": "HTTPS",
  "toPorts": "443"
}

Supprimer une relation

DELETE /api/relations/:id

---

Codes d'erreur

Code HTTP	Description
200	Succès
201	Ressource créée
400	Requête invalide (voir error dans la réponse)
401	Non authentifié (token manquant ou expiré)
403	Accès refusé (rôle insuffisant)
404	Ressource introuvable
409	Conflit (email déjà utilisé, etc.)
429	Trop de requêtes (rate limiting)
500	Erreur serveur interne

Format des erreurs :

{
  "error": "Description lisible de l'erreur"
}