# Démarrage

> De la clé au premier appel : créer une clé, puis interroger un outil, un agent ou un client MCP.

Source: https://piqline.com/fr/docs/api

L’API de Piqline donne à vos scripts et à vos agents l’accès à votre workspace : les mêmes outils et les mêmes agents que l’assistant du dashboard, par HTTP ou par MCP (Model Context Protocol). Chaque appel porte sur un seul workspace, avec les droits du membre qui a créé la clé.

## Ce qu’il faut avoir

- Un workspace Piqline dont vous êtes owner ou admin. Les membres voient la page des clés en lecture seule.
- Un outil qui envoie des requêtes HTTP (`curl` dans les exemples) ou un client MCP.

## 1. Créer une clé

1. Ouvrez [Settings → API and MCP](/settings/api).
2. Nommez la clé, cochez ses scopes (commencez par `read`) et choisissez une expiration.
3. Cliquez sur **Create key**, puis copiez la clé. Elle ne s’affiche qu’une fois.

> **Attention.** La clé agit avec vos droits sur le workspace. Gardez-la dans un gestionnaire de secrets ou une variable d’environnement, jamais dans le code ni dans un dépôt. Si elle fuit, révoquez-la depuis la même page.

Rangez-la dans une variable d’environnement :

```bash
export PIQLINE_API_KEY="piq_live_…"
```

## 2. Vérifier la clé

```bash tab="curl"
curl -s https://piqline.com/api/v1/workspace \
  -H "Authorization: Bearer $PIQLINE_API_KEY"
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/workspace", {
  headers: { Authorization: "Bearer " + process.env.PIQLINE_API_KEY },
});
const data = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.get(
    "https://piqline.com/api/v1/workspace",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
)
data = response.json()
```

Réponse :

```json
{
  "workspace": { "id": "b7a1c3e0-5d2f-4c8a-9e41-2f6d0a7b1c93", "name": "Atelier" },
  "key": {
    "id": "0d4e8f2a-71c6-4b3d-8a55-c9e2b6f10d47",
    "name": "Claude Code",
    "prefix": "piq_live_Ab12Cd",
    "scopes": ["read", "agents"]
  },
  "acting_as": {
    "user_id": "3c9a52e1-8b47-4d06-a2f3-71e0b5d4c689",
    "email": "vous@exemple.fr",
    "role": "owner"
  },
  "limits": {
    "requests_per_minute": 120,
    "agent_runs_per_minute": 10,
    "requests_per_day": 20000,
    "requests_today": 1
  }
}
```

`key.scopes` liste ce que la clé peut faire, et `limits` ce qu’il lui reste. Un `401` signale une clé absente, mal copiée ou révoquée : voir [Erreurs](/fr/docs/api/errors).

## 3. Appeler un outil

Un outil est une capacité de l’assistant : lire le corpus, chercher en direct, écrire, agir. Cet exemple lit les volumes de collecte des 7 derniers jours :

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/getCoverageStats \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period":"7d"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/getCoverageStats", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ period: "7d" }),
});
const data = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/getCoverageStats",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={"period": "7d"},
)
data = response.json()
```

La réponse porte le nom de l’outil et sa sortie (abrégée ici) :

```json
{
  "tool": "getCoverageStats",
  "output": {
    "period": "7d",
    "itemsTotal": 1842,
    "itemsPeriod": 214,
    "items24h": 37,
    "sources": 12,
    "byPlatform": [{ "platform": "rss", "items": 904, "items24h": 20 }]
  }
}
```

Les 92 outils appelables, leurs scopes et leurs entrées sont décrits dans le [catalogue](/fr/docs/api/tools#catalogue).

## 4. Interroger un agent

Un agent enchaîne plusieurs outils et répond en langage naturel. La clé doit porter le scope `agents`, et les scopes des outils que l’agent peut utiliser.

```bash tab="curl"
curl -s https://piqline.com/api/v1/agents/piqline \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Combien de sources suit ce workspace, et lesquelles sont en erreur ?"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/agents/piqline", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: "Combien de sources suit ce workspace, et lesquelles sont en erreur ?" }),
});
const data = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/agents/piqline",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={"input": "Combien de sources suit ce workspace, et lesquelles sont en erreur ?"},
)
data = response.json()
```

Réponse, abrégée :

```json
{
  "agent": "piqline",
  "status": "completed",
  "text": "Le workspace suit 12 sources, dont 2 en erreur : …",
  "tool_calls": [{ "tool": "listSources", "state": "output-available" }],
  "pending": []
}
```

La suite est dans [Agents](/fr/docs/api/agents).

## 5. Connecter un client MCP

Avec Claude Code :

```bash
claude mcp add --transport http piqline https://piqline.com/api/mcp \
  --header "Authorization: Bearer $PIQLINE_API_KEY"
```

Les autres clients sont décrits dans [Serveur MCP](/fr/docs/api/mcp).

## Pas encore disponible

- **Webhooks.** Aucun envoi vers vos systèmes. Pour suivre ce qui arrive, interrogez `getSignals` ou `searchItems` à intervalle régulier.
- **SDK officiels.** Le [document OpenAPI](https://piqline.com/api/v1/openapi.json) décrit chaque route : un générateur de client en tire un SDK dans votre langage.
- **Connexion OAuth.** Seules les clés sont acceptées. Les connecteurs qui exigent OAuth, comme ceux de claude.ai et de ChatGPT, ne peuvent pas encore se brancher.
- **Export en masse.** Les outils rendent des pages de résultats bornées (40 items au plus pour `searchItems`).
