> 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/v4.7-en/data-and-ai-project/datasets/utiliser-lapi-dataset.md).

# Use the dataset API

Make your data securely accessible via a REST API.

Each Dataset published in Cleyrop is exposed via a **secure access API.** This makes it possible to query, filter, or consume the data from an external application, an internal service, or an automated script.

A **documentation** complete overview of the API content and parameters is available:

* **URL** : https\://***\<your\_domain>***/data-serve/swagger-ui/index.html
* **Description** : This Swagger describes the available endpoints for accessing datasets.

***

## Create an access token

To use the API, you must generate an authentication token.

{% hint style="danger" %}
This token is **personal and has the same access permissions as your account** across all datasets.
{% endhint %}

**Creation steps**

1. Click on your username at the bottom left of the platform.
2. Select **My profile**.
3. Click on **Create a token**.
4. Enter a token name and a validity period.
   * Default duration: 1 year
   * The token inherits the user's rights that generated it.

{% hint style="info" %}
The token value **is visible only once**when it is created. Keep it in a secure place (e.g. password manager).
{% endhint %}

### Revoke a token

To delete an existing token:

1. Go to the My profile → Token list page.
2. Click the 🗑️ icon at the end of the row corresponding to the token.
3. Enter delete to confirm revocation.

Once revoked, the token can no longer be used to access the API.

## Use the Dataset API

The API is accessible via the following URL:

* https\://***\<your\_domain>***/data-serve/api/v1/datasets/

| your\_domain | The domain of your Cleyrop platform (e.g. cleyrop.entreprise.cleyrop.tech). |
| ------------ | --------------------------------------------------------------------------- |
| techname     | The unique ID of the dataset to expose (visible in its Dataset record).     |

The token must be passed in the **header** of the HTTP request, with the TOKEN key.

#### Available routes

<table><thead><tr><th width="109.6689453125">Method</th><th width="346.2607421875">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 token.</td></tr><tr><td>GET</td><td>/data-serve/api/v1/datasets</td><td>Retrieves the <strong>content</strong> of a dataset by its ID.</td></tr><tr><td>GET</td><td>/data-serve/api/v1/datasets/structured</td><td>Retrieves a dataset with a structured JSON response.</td></tr><tr><td>GET</td><td>/data-serve/api/v1/datasets/metadata</td><td>Retrieves all of the <strong>metadata</strong> for a dataset</td></tr><tr><td>POST</td><td>/data-serve/api/v1/datasets/sql/query</td><td>Runs a SQL query on all accessible datasets.</td></tr><tr><td>POST</td><td>/data-serve/api/v1/projects/{projectID}/datasets/sql/query</td><td>Runs a <strong>SQL query</strong> on the datasets of a specific project.<br>The <strong>column description</strong> is visible in the results</td></tr></tbody></table>

### List the datasets

The Cleyrop API allows listing the datasets available to a user (catalog internal, those authorized in the projects of which they are a member)

### Read a dataset

**CURL request example**

*Replace techname with the unique identifier of your Dataset and token with yours.*

{% code title="dataset API call" %}

```bash
curl 'https://cleyrop.maplateforme.net/data-serve/api/v1/datasets/techname' \
     -H 'TOKEN: my_great_token_689371'
```

{% endcode %}

**Useful information:**

* The returned data depends on the token's permissions (restricted or full access).
* After each use, the token's last-used date is updated in your profile.
* You can also use the API from Python, PowerBI, or any REST-compatible tool.

### Filter the data with a SQL query

The Cleyrop API also allows executing a **SQL query** directly in the call to filter the returned data.

This makes it possible to query only the useful portion of a dataset without having to retrieve all of the content.

```bash
curl 'https://cleyrop.maplateforme.net/data-serve/api/v1/datasets/techname?query=SELECT%20*%20FROM%20dataset%20WHERE%20pays%3D%27France%27%20AND%20revenu%20%3E%205000' \
     -H 'TOKEN: my_great_token_689371'
```

💡 *Special characters must be URL-encoded* (e.g. spaces → %20, quotation marks → %27).

#### Recommendations

* The query must be a **SQL statement** supported by the API (SELECT only).
* The keyword FROM dataset refers to the dataset exposed by the API.
* You can combine WHERE, AND, OR, LIMIT, ORDER BY… conditions

{% hint style="info" %}
The results of the `POST /data-serve/api/v1/datasets/sql/query` are **paginated** : `size` defines the number of rows per page (10 by default, **5,000 maximum**) and `page` the page number. The sorting requested with `ORDER BY` is respected in the returned pages.
{% endhint %}

***

## Best practices

* Never **never share** your token publicly (code, requests, screenshots).
* Prefer **dedicated tokens per use** (e.g. one token per client application).
* Monitor the last-used date to identify inactive access.
* Revoke tokens that have not been used for more than 90 days.