API du Pod

Le Pod (application serveur SUMARiS) expose plusieurs API, toutes servies par le même serveur :

API	Point d'accès	Usage
Documentation en ligne	<PEER_URL>/api	Page d'accueil de la documentation et des outils du Pod
GraphQL	<PEER_URL>/graphql	Accès aux données (lecture/écriture), utilisée par l'App
GraphQL (abonnements)	<PEER_URL>/graphql/websocket	Notifications en temps réel (WebSocket)
REST	<PEER_URL>/api/...	Référentiels, extractions, informations sur le nœud, images...
Serveur MCP	<PEER_URL>/api/mcp	Outils métier pour les assistants IA (Claude, ChatGPT, Mistral...)
Chat compatible OpenAI	<PEER_URL>/api/v1	Proxy LLM utilisant les outils métier du Pod

<PEER_URL> désigne l'adresse du Pod, par exemple http://localhost:8080 pour un Pod lancé en local (cf. Pod : installation). Dans les exemples ci-dessous, elle est lue dans une variable d'environnement :

export PEER_URL="http://localhost:8080"

Documentation en ligne du Pod

Chaque Pod publie sa propre documentation, toujours à jour avec sa version, à l'adresse <PEER_URL>/api :

Page	Adresse	Contenu
Accueil	<PEER_URL>/api	Liens vers la documentation et les outils ci-dessous
Swagger UI	<PEER_URL>/api/swagger-ui	Liste des points d'accès REST, avec exécution de requêtes depuis le navigateur
Définition OpenAPI	<PEER_URL>/v3/api-docs	Description OpenAPI 3 (JSON) de l'API REST, pour générer un client
GraphiQL	<PEER_URL>/api/graphiql	Éditeur de requêtes GraphQL, avec auto-complétion et documentation du schéma
Abonnements GraphQL	<PEER_URL>/graphql/websocket/test	Éditeur de requêtes d'abonnement (WebSocket)
Fonctionnalités IA	<PEER_URL>/api/ai	Serveur MCP et API de chat : configuration des clients, liste des outils
Documentation des extractions	<PEER_URL>/api/extraction/doc	Formats d'extraction disponibles sur le Pod

Les raccourcis <PEER_URL>/api/docs et <PEER_URL>/swagger-ui.html redirigent vers Swagger UI.

Authentification

L'accès aux données publiques (référentiels) est anonyme. Les autres données nécessitent d'être authentifié, avec les mêmes droits que l'utilisateur dans l'App.

Pour un script ou un outil externe, le plus simple est d'utiliser un jeton d'API personnel :

1. se connecter à l'App reliée au Pod ;
2. ouvrir la page Mon compte > Jetons et créer un jeton ;
3. copier sa valeur (affichée une seule fois) dans une variable d'environnement, jamais dans un fichier versionné :

export SUMARIS_API_KEY="<valeur du jeton>"

Le jeton est transmis dans l'en-tête HTTP Authorization, sous l'une des formes :

• Authorization: Bearer <jeton> : format standard, utilisé par les clients MCP et les bibliothèques OpenAI ;
• Authorization: token <jeton> : format utilisé par l'App.

Un jeton peut être révoqué à tout moment depuis la même page Mon compte > Jetons.

API GraphQL

L'API GraphQL est l'API principale du Pod : l'App l'utilise pour toutes ses lectures et écritures de données.

• Point d'accès : POST <PEER_URL>/graphql (corps JSON {"query": "...", "variables": {...}}) ;
• Schéma complet (SDL) : GET <PEER_URL>/graphql/schema ;
• Éditeur interactif : <PEER_URL>/api/graphiql (l'onglet Docs permet de parcourir les requêtes et les types).

Exemple, lecture anonyme d'un référentiel (les pays) :

curl "$PEER_URL/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ referentials(entityName: \"Location\", filter: {levelIds: [1]}, size: 2) { id label name } }"}'
# => {"data":{"referentials":[{"id":3,"label":"BEL","name":"Belgium"},{"id":1,"label":"FRA","name":"France"}]}}

Exemple, requête authentifiée :

curl "$PEER_URL/graphql" \
  -H "Authorization: Bearer $SUMARIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ account { id firstName lastName } }"}'

La liste des entités de référentiel interrogeables est donnée par la requête { referentialTypes { id } }.

Abonnements (WebSocket)

Les abonnements GraphQL (subscriptions) permettent à l'App d'être notifiée des modifications (mise à jour d'une donnée, nouveaux messages, progression d'un traitement...). Ils passent par une connexion WebSocket sur <PEER_URL>/graphql/websocket. La page <PEER_URL>/graphql/websocket/test permet de tester une requête d'abonnement.

API REST

L'API REST complète l'API GraphQL pour des usages plus simples ou des téléchargements de fichiers. Sa documentation de référence est Swagger UI (<PEER_URL>/api/swagger-ui), générée à partir du code du Pod, avec la définition OpenAPI correspondante (<PEER_URL>/v3/api-docs).

Principaux groupes de points d'accès :

Chemin	Usage
/api/node/info	Nom et version du Pod
/api/node/health	État de santé du Pod et de ses composants (base de données, IA...)
/api/referential/...	Liste des types de référentiels, recherche dans un référentiel
/api/extraction/...	Types d'extraction, téléchargement des extractions, documentation des formats
/api/feed	Flux d'actualités du Pod (JSON Feed)
/api/image/..., /api/avatar/..., /api/logo/...	Images (photos, avatars, logos)

Exemples :

# Version du Pod
curl "$PEER_URL/api/node/info"

# Types de référentiels, puis recherche de lieux
curl "$PEER_URL/api/referential/list"
curl "$PEER_URL/api/referential/Location/search?size=2"

# Types d'extraction disponibles
curl "$PEER_URL/api/extraction/types"

Serveur MCP (assistants IA)

Le Pod est un serveur MCP (Model Context Protocol) : un assistant IA (Claude, ChatGPT, Mistral, Copilot, LLM local...) peut s'y connecter et appeler lui-même les outils métier du Pod.

• Point d'accès : <PEER_URL>/api/mcp, transport Streamable HTTP ;
• Sans jeton : seuls les outils de référentiel publics sont utilisables (espèces, engins, lieux, unités...) ;
• Avec un jeton : les outils sur les programmes, stratégies, marées et le profil utilisateur sont aussi utilisables, dans la limite des droits de l'utilisateur.

La page <PEER_URL>/api/ai liste les outils réellement disponibles sur le Pod. À titre indicatif :

Domaine	Outils
Référentiels	ref_search_species, ref_search_referential, ref_list_programs, ref_get_program
Programmes	program_search, program_get, program_save
Stratégies	strategy_search, strategy_get, strategy_save
Marées	trip_search, trip_get
Utilisateur	person_me (vérifie le jeton et identifie l'utilisateur)

Exemple, ajout du serveur dans Claude Code :

claude mcp add --transport http sumaris "$PEER_URL/api/mcp" \
  --header "Authorization: Bearer $SUMARIS_API_KEY"

Exemple, configuration JSON (fichier .mcp.json de Claude Code, Cursor, Windsurf...) :

{
  "mcpServers": {
    "sumaris": {
      "type": "http",
      "url": "<PEER_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer ${SUMARIS_API_KEY}"
      }
    }
  }
}

Le serveur MCP est activé par l'option spring.ai.mcp.server.enabled du Pod. La page <PEER_URL>/api/ai détaille aussi la configuration des clients ne supportant que les serveurs locaux (passerelle mcp-remote) et un exemple de prompt pour connecter un assistant.

API de chat compatible OpenAI

Le Pod peut aussi servir de proxy LLM, compatible avec l'API Chat Completions d'OpenAI. Le fournisseur de LLM (et sa clé) est configuré sur le Pod : le client n'a besoin que de son jeton SUMARiS. Le LLM peut appeler les mêmes outils métier que le serveur MCP, avec les droits de l'utilisateur.

Paramètre du client OpenAI	Valeur
Base URL	<PEER_URL>/api/v1
API key	le jeton SUMARiS (SUMARIS_API_KEY)
Model	un modèle listé par GET <PEER_URL>/api/v1/models, ou default

curl "$PEER_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $SUMARIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "default", "messages": [{"role": "user", "content": "Quels programmes de collecte me sont accessibles ?"}]}'

Limites : seuls POST /api/v1/chat/completions et GET /api/v1/models sont disponibles, sans streaming. L'API est activée par l'option sumaris.ai.chat.enabled (options sumaris.ai.chat.* du Pod). Voir <PEER_URL>/api/ai pour les pièces jointes, les conversations et les codes d'erreur.