> For the complete documentation index, see [llms.txt](https://cleyrop.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cleyrop.gitbook.io/docs/support-and-ressources/references-techniques-api-sdk.md).

# Références techniques (API, SDK)

Cette section regroupe l’ensemble des ressources techniques nécessaires pour interagir avec la plateforme Cleyrop :

* **APIs REST** (Assistant AI, Data Serve) pour exposer ou consommer des données.
* **Librairies Python** (PyAI Cleyrop, S3 Connector) pour automatiser les traitements et développer des apps.
* Documentation **outils et frameworks tiers**

Elle s’adresse principalement aux data engineers, développeurs IA, et intégrateurs, souhaitant aller au-delà de l’usage standard de la plateforme et connecter Cleyrop à leurs applications ou pipelines externes.

## API Publiques - Swagger

### API Dataset

L’API Data Serve permet d’exposer et d’interroger les datasets de la plateforme Cleyrop via HTTP.

Elle constitue la brique d’interopérabilité entre la donnée gouvernée et les applications externes (dashboards, assistants IA, apps Gradio…).

Documentation Swagger :

* **URL** : https\://***\<votre\_domaine>***/data-serve/swagger-ui/index.html
* **Description** : Ce Swagger décrit les endpoints disponibles pour accéder aux datasets.
* **Authentification** : via token utilisateur ou token projet (header TOKEN:).
* **Identifiant dataset :** Identifiant unique (*project.dataset\_name*)

Le Token est à [générer dans la page Profil & Token](/docs/projet-data-and-ia/datasets/utiliser-lapi-dataset.md) : Nom Utilisateur > Profil & token

Routes disponibles :

<table><thead><tr><th width="137.51953125">Méthode</th><th>Route</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/data-serve/api/v1/datasets</td><td>Liste tous les datasets accessibles par l’utilisateur.</td></tr><tr><td>GET</td><td>/data-serve/api/v1/datasets/{datasetId}</td><td>Récupère les données du dataset</td></tr><tr><td>GET</td><td>/data-serve/api/v1/datasets/{datasetId}/metadata</td><td>Récupère les <strong>métadonnées</strong> et le contenu d’un dataset par son ID.</td></tr><tr><td>GET</td><td>/data-serve/api/v1/datasets/structured/{datasetId}</td><td>Récupère les données du dataset avec une réponse JSON structurée</td></tr><tr><td>POST</td><td>/data-serve/api/v1/datasets/sql/query</td><td>Exécute une <strong>requête SQL</strong> sur l’ensemble des datasets accessibles.</td></tr><tr><td>POST</td><td>/data-serve/api/v1/projects/{projectID}/datasets/sql/query</td><td>Exécute une <strong>requête SQL</strong> sur les datasets d’un projet spécifique.</td></tr></tbody></table>

**Accès depuis un environnement interne à la plateforme :**

Depuis un DevSpace ou App, l'API Dataset est également accessible via la route interne : `http://apisix-gateway.cleyrop.svc.cluster.local/data-serve/api/v1`

Les endpoints et l'authentification sont identiques.

#### Moteur SQL utilisé

Les requêtes exécutées via l'API Data Serve utilisent le moteur **Trino SQL**, tandis que les transformations dans un Dataflow utilisent **Spark SQL**.

La syntaxe de base est identique, mais certaines fonctions peuvent diverger.

Référez-vous à la documentation Spark SQL et Trino pour le détail des fonctions disponibles.

### API Corpus

L'API Corpus permet de lister et d'interroger les corpus de documents publiés sur la plateforme.

Documentation Swagger :

* **URL** : <https://api.\\>\<votre\_domaine>/ai-gen-assistant/api/docs
* **Base API** : <https://api.\\>\<votre\_domaine>/ai-gen-assistant/api/v1
* **Auth** : header Token: \<TOKEN> (token projet généré depuis l'onglet *Tokens*)

Le Token est à [générer dans la page Profil & Token](/docs/projet-data-and-ia/datasets/utiliser-lapi-dataset.md) : Nom Utilisateur > Profil & token

Routes disponibles :

<table><thead><tr><th width="145.5546875">Méthode</th><th width="215.09765625">Route</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/v1/corpora</td><td>Liste tous les corpus accessibles, avec leurs métadonnées.</td></tr><tr><td>POST</td><td>/v1/corpora/search</td><td>Effectue une recherche dans un ou plusieurs corpus.</td></tr></tbody></table>

**Accès depuis un environnement interne à la plateforme :**

Depuis un DevSpace, une Agent App ou un Dataflow, l'API est également accessible via la route interne : `http://apisix-gateway.cleyrop.svc.cluster.local/ai-gen-assistant/api/v1`

Les endpoints et l'authentification sont identiques.

### API Assistants IA

L’API des Assistants IA permet d'interroger les assistants publiés sur la plateforme.

Documentation Swagger :

* **URL** : <https://api.cleyrop.\\>\<votre\_domaine>/api/docs
* **Base API** : <https://api.cleyrop.\\>\<votre\_domaine>/api/v1
* **Auth** : header apiKey: \<TOKEN> (token projet/assistant généré depuis l’onglet *Tokens*).

Le Token est à [générer dans le Projet](/docs/projet-data-and-ia/studio-ai/utiliser-un-assistant-dans-un-systeme-metier.md) : Accueil Projet > Token ou Projet > Assistant IA > Fiche Assistant

Routes disponibles :

<table><thead><tr><th width="128.2578125">Méthode</th><th>Route</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/v1/assistants/{assistant_id}</td><td>Récupère les métadonnées d’un assistant (nom, type, configuration).</td></tr><tr><td>POST</td><td>/v1/assistants/{assistant_id}/execute</td><td>Exécute une requête sur un assistant (prompt textuel ou JSON).</td></tr><tr><td>POST</td><td>/v1/assistants/{assistant_id}/sessions</td><td>Crée une nouvelle session utilisateur pour une conversation.</td></tr><tr><td>POST</td><td>/v1/assistants/{assistant_id}/sessions/{session_id}/file_storage</td><td>Upload de fichiers associés à la session (utilisé pour les assistants RAG).</td></tr></tbody></table>

## Librairies et SDK

### **Librairie Python — pyai\_cleyrop**

La documentation technique détaillée de la librairie Python utilisée pour les apps est disponible ici :

👉 [Cleyrop Components Documentation](/docs/support-and-ressources/references-techniques-api-sdk/sdk-py-ai-cleyrop.md)

Le framework sous-jacent est LangChain, permettant d’orchestrer les appels aux modèles, chaînes et outils.

👉 Voir la documentation officielle : <https://python.langchain.com>

Cette librairie permet :

* d’interagir avec les **modèles LLM** de Cleyrop (ChatCleyrop)
* de générer des **embeddings** (EmbeddingsCleyrop)
* de détecter automatiquement les **langues** des documents

**Compatibilité** :

* ✅ Clusters Python 3.11 / 3.12
* 🚫 Non compatible avec 3.13
* 📦 Disponible dans les Dataflows Python et Codelab Jupyter

### Cleyrop S3 Connector

Librairie Python pour [interagir avec les **Données de travail**](/docs/projet-data-and-ia/donnees-de-travail-fichiers/utiliser-les-donnees-dans-un-script.md) des projets qui sont buckets S3 utilisés par Cleyrop. Elle gère automatiquement les endpoints configurés et l'authentification sécurisée.

Cette librairie permet :

* lire ou créer des fichiers
* explorer et interagir avec la liste des fichiers

<table data-full-width="true"><thead><tr><th>Méthode</th><th>Description</th><th width="432.4140625">Paramètres attendus</th><th>Type de retour</th></tr></thead><tbody><tr><td><code>discover</code></td><td>Lister les fichiers d’un dossier</td><td><code>{"key": "path_dossier"}</code></td><td>DataFrame Pandas</td></tr><tr><td><code>read_bytes</code></td><td>Lire un fichier binaire</td><td><code>{"path": "path_fichier"}</code></td><td><code>bytes</code></td></tr><tr><td><code>get_df</code></td><td>Charger un fichier tabulaire</td><td><code>{"key": "path_fichier"}</code> (+ <code>sheet_name</code>)</td><td>DataFrame Pandas</td></tr><tr><td><code>write_bytes</code></td><td>Écrire un fichier</td><td><code>{"path": "...", "body": bytes}</code></td><td><code>None</code></td></tr><tr><td><code>move</code></td><td>Déplacer un fichier</td><td><code>{"source_key": "...", "destination_key": "..."}</code></td><td><code>None</code></td></tr><tr><td><code>delete</code></td><td>Supprimer un fichier</td><td><code>{"key": "path_fichier"}</code></td><td><code>None</code></td></tr></tbody></table>

## Documentation outils tiers

### **Tools - Protocole MCP**

Les Tools sont des serveurs MCP qui permettent d’exposer des **outils** (tools) accessibles aux **assistants, aux apps** déployés sur la plateforme et au Druide.

Ils suivent le [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), un protocole standardisé pour connecter des applications à des LLMs et partager du contexte (fichiers, outils, APIs, etc.) de manière structurée et sécurisée.

Chaque serveur MCP est un microservice hébergé sur la plateforme, accessible via un endpoint HTTP, qui déclare dynamiquement les **outils disponibles**.

### Datavisualisation

{% hint style="warning" %}
La DataVisualisation est disponible uniquement pour les clients ayant souscrit avant mai 2026. Cette fonctionnalité a été décommissionnée pour les clients à partir de cette date.
{% endhint %}

Toucan Toco V2 est l’outil de data visualisation intégré à Cleyrop, utilisé pour créer et publier des dashboards interactifs.

📘 Documentation officielle :[ documentation officielle de Toucan Toco](https://docs.toucantoco.com/).

Principales intégrations avec Cleyrop :

* Liaison directe entre datasets du projet et app Toucan.
* Rafraîchissement des données (/staging/refresh).
* Authentification et permissions gérées côté Cleyrop.