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

# Use the dataset 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** full content and API parameter documentation 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 **Create a token**.
4. Enter a token name and a validity period.
   * Default duration: 1 year
   * The token inherits the rights of the user who generates it.

{% hint style="info" %}
The token value **is visible only once**upon creation. 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. Type 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 sheet).      |

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 a dataset's <strong>metadata</strong> metadata</td></tr><tr><td>POST</td><td>/data-serve/api/v1/datasets/sql/query</td><td>Executes an SQL query on all accessible datasets.</td></tr><tr><td>POST</td><td>/data-serve/api/v1/projects/{projectID}/datasets/sql/query</td><td>Executes an <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 datasets

The Cleyrop API allows you to list available datasets for a user (internal catalog, 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 the 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 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 data with an SQL query

The Cleyrop API also allows you to execute 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 the entire 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, quotes → %27).

#### Recommendations

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

***

## Best practices

* Never **never share** your token publicly (code, queries, screenshots).
* Prefer **dedicated tokens by use case** (e.g. one token per client application).
* Monitor the last used date to identify inactive accesses.
* Revoke tokens not used for more than 90 days.