> 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/documentation-fr-en/support-and-resources/references-techniques-api-sdk.md).

# Technical references (API, SDK)

This section brings together all the technical resources needed to interact with the Cleyrop platform:

* **REST APIs** (Assistant AI, Data Serve) to expose or consume data.
* **Python libraries** (PyAI Cleyrop, S3 Connector) to automate processing and develop apps.
* Documentation **third-party tools and frameworks**

It is mainly intended for data engineers, AI developers, and integrators who want to go beyond standard use of the platform and connect Cleyrop to their external applications or pipelines.

## Public APIs - Swagger

### Dataset API

The Data Serve API lets you expose and query the Cleyrop platform datasets via HTTP.

It is the interoperability building block between governed data and external applications (dashboards, AI assistants, Gradio apps...).

Swagger documentation:

* **URL** : https\://***\<your\_domain>***/data-serve/swagger-ui/index.html
* **Description** : This Swagger describes the endpoints available for accessing datasets.
* **Authentication** : via user token or project token (header TOKEN:).
* **Dataset ID:** Unique identifier (*project.dataset\_name*)

The token must be [generated on the Profile & Token page](/docs/documentation-fr-en/data-and-ai-project/datasets/utiliser-lapi-dataset.md) : User Name > Profile & token

Available routes:

<table><thead><tr><th width="137.51953125">Method</th><th>Route</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/data-serve/api/v1/datasets</td><td>Lists all datasets accessible by the user.</td></tr><tr><td>GET</td><td>/data-serve/api/v1/datasets/{datasetId}</td><td>Retrieves the dataset data</td></tr><tr><td>GET</td><td>/data-serve/api/v1/datasets/{datasetId}/metadata</td><td>Retrieves the <strong>metadata</strong> and the contents of a dataset by its ID.</td></tr><tr><td>GET</td><td>/data-serve/api/v1/datasets/structured/{datasetId}</td><td>Retrieves the dataset data with a structured JSON response</td></tr><tr><td>POST</td><td>/data-serve/api/v1/datasets/sql/query</td><td>Executes a <strong>SQL query</strong> on all accessible datasets.</td></tr><tr><td>POST</td><td>/data-serve/api/v1/projects/{projectID}/datasets/sql/query</td><td>Executes a <strong>SQL query</strong> on the datasets of a specific project.</td></tr></tbody></table>

**Access from an internal environment on the platform:**

From a DevSpace or App, the Dataset API is also accessible via the internal route: `http://apisix-gateway.cleyrop.svc.cluster.local/data-serve/api/v1`

The endpoints and authentication are identical.

#### SQL engine used

Queries executed via the Data Serve API use the **Trino SQL**, while transformations in a Dataflow use **Spark SQL**.

The basic syntax is identical, but some functions may differ.

Refer to the Spark SQL and Trino documentation for details of the available functions.

### Corpus API

The Corpus API lets you list and query the document corpora published on the platform.

Swagger documentation:

* **URL** : <https://api.\\>\<your\_domain>/ai-gen-assistant/api/docs
* **API base** : <https://api.\\>\<your\_domain>/ai-gen-assistant/api/v1
* **Auth** : header Token: \<TOKEN> (project token generated from the tab *Tokens*)

The token must be [generated on the Profile & Token page](/docs/documentation-fr-en/data-and-ai-project/datasets/utiliser-lapi-dataset.md) : User Name > Profile & token

Available routes:

<table><thead><tr><th width="145.5546875">Method</th><th width="215.09765625">Route</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/v1/corpora</td><td>Lists all accessible corpora, with their metadata.</td></tr><tr><td>POST</td><td>/v1/corpora/search</td><td>Performs a search in one or more corpora.</td></tr></tbody></table>

**Access from an internal environment on the platform:**

From a DevSpace, an Agent App or a Dataflow, the API is also accessible via the internal route: `http://apisix-gateway.cleyrop.svc.cluster.local/ai-gen-assistant/api/v1`

The endpoints and authentication are identical.

### AI Assistants API

The AI Assistants API lets you query the assistants published on the platform.

Swagger documentation:

* **URL** : <https://api.cleyrop.\\>\<your\_domain>/api/docs
* **API base** : <https://api.cleyrop.\\>\<your\_domain>/api/v1
* **Auth** : header apiKey: \<TOKEN> (project/assistant token generated from the tab *Tokens*).

The token must be [generated in the Project](/docs/documentation-fr-en/data-and-ai-project/studio-ai/utiliser-un-assistant-dans-un-systeme-metier.md) : Project Home > Token or Project > AI Assistant > Assistant Details

Available routes:

<table><thead><tr><th width="128.2578125">Method</th><th>Route</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/v1/assistants/{assistant_id}</td><td>Retrieves an assistant's metadata (name, type, configuration).</td></tr><tr><td>POST</td><td>/v1/assistants/{assistant_id}/execute</td><td>Executes a query on an assistant (text or JSON prompt).</td></tr><tr><td>POST</td><td>/v1/assistants/{assistant_id}/sessions</td><td>Creates a new user session for a conversation.</td></tr><tr><td>POST</td><td>/v1/assistants/{assistant_id}/sessions/{session_id}/file_storage</td><td>File upload associated with the session (used for RAG assistants).</td></tr></tbody></table>

## Libraries and SDKs

### **Python library — pyai\_cleyrop**

Detailed technical documentation for the Python library used for apps is available here:

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

The underlying framework is LangChain, allowing orchestration of model, chain, and tool calls.

👉 See the official documentation: <https://python.langchain.com>

This library allows:

* to interact with the **LLM models** of Cleyrop (ChatCleyrop)
* to generate **embeddings** (EmbeddingsCleyrop)
* to automatically detect the **languages** of documents

**Compatibility** :

* ✅ Python 3.11 / 3.12 clusters
* 🚫 Not compatible with 3.13
* 📦 Available in Python Dataflows and Codelab Jupyter

### Cleyrop S3 Connector

Python library to [interact with the **Work Data**](/docs/documentation-fr-en/data-and-ai-project/donnees-de-travail-fichiers/utiliser-les-donnees-dans-un-script.md) of projects which are S3 buckets used by Cleyrop. It automatically manages configured endpoints and secure authentication.

This library allows:

* read or create files
* browse and interact with the list of files

<table data-full-width="true"><thead><tr><th>Method</th><th>Description</th><th width="432.4140625">Expected parameters</th><th>Return type</th></tr></thead><tbody><tr><td><code>discover</code></td><td>List files in a folder</td><td><code>{"key": "folder_path"}</code></td><td>Pandas DataFrame</td></tr><tr><td><code>read_bytes</code></td><td>Read a binary file</td><td><code>{"path": "file_path"}</code></td><td><code>bytes</code></td></tr><tr><td><code>get_df</code></td><td>Load a tabular file</td><td><code>{"key": "file_path"}</code> (+ <code>sheet_name</code>)</td><td>Pandas DataFrame</td></tr><tr><td><code>write_bytes</code></td><td>Write a file</td><td><code>{"path": "...", "body": bytes}</code></td><td><code>None</code></td></tr><tr><td><code>move</code></td><td>Move a file</td><td><code>{"source_key": "...", "destination_key": "..."}</code></td><td><code>None</code></td></tr><tr><td><code>delete</code></td><td>Delete a file</td><td><code>{"key": "file_path"}</code></td><td><code>None</code></td></tr></tbody></table>

## Third-party tools documentation

### **Tools - MCP Protocol**

Tools are MCP servers that make it possible to expose **tools** (tools) accessible to **assistants, apps** deployed on the platform and to Druide.

They follow the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), a standardized protocol for connecting applications to LLMs and sharing context (files, tools, APIs, etc.) in a structured and secure way.

Each MCP server is a microservice hosted on the platform, accessible via an HTTP endpoint, which dynamically declares the **available tools**.

### Data visualization

{% hint style="warning" %}
DataVisualization is available only for customers who subscribed before May 2026. This feature has been decommissioned for customers as of that date.
{% endhint %}

Toucan Toco V2 is the data visualization tool integrated into Cleyrop, used to create and publish interactive dashboards.

📘 Official documentation:[ Toucan Toco official documentation](https://docs.toucantoco.com/).

Main integrations with Cleyrop:

* Direct link between project datasets and Toucan app.
* Data refresh (/staging/refresh).
* Authentication and permissions managed on Cleyrop's side.