# Schnellstart

> Vom Schlüssel zum ersten Aufruf: Schlüssel erstellen, dann ein Tool, einen Agenten oder einen MCP-Client ansprechen.

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

Die Piqline-API gibt Ihren Skripten und Agenten Zugriff auf Ihren Workspace: dieselben Tools und dieselben Agenten wie der Assistent im Dashboard, über HTTP oder MCP (Model Context Protocol). Jeder Aufruf wirkt auf einen Workspace, mit den Rechten des Mitglieds, das den Schlüssel erstellt hat.

## Was Sie brauchen

- Einen Piqline-Workspace, in dem Sie Owner oder Admin sind. Mitglieder sehen die Seite für Schlüssel nur lesend.
- Ein Tool, das HTTP-Anfragen sendet (in den Beispielen `curl`), oder einen MCP-Client.

## 1. Schlüssel erstellen

1. Öffnen Sie [Einstellungen → API und MCP](/settings/api).
2. Benennen Sie den Schlüssel, wählen Sie seine Scopes (beginnen Sie mit `read`) und ein Ablaufdatum.
3. Klicken Sie auf **Schlüssel erstellen** und kopieren Sie den Schlüssel. Er wird nur einmal angezeigt.

> **Warnung.** Der Schlüssel handelt mit Ihren Rechten im Workspace. Bewahren Sie ihn in einem Secrets-Manager oder einer Umgebungsvariable auf, nie im Code oder in einem Repository. Wenn er offengelegt wird, widerrufen Sie ihn auf derselben Seite.

Legen Sie ihn in einer Umgebungsvariable ab:

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

## 2. Schlüssel prüfen

```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()
```

Antwort:

```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` listet, was der Schlüssel darf, und `limits`, was ihm noch bleibt. Ein `401` bedeutet: Der Schlüssel fehlt, wurde falsch kopiert oder widerrufen. Siehe [Fehler](/de/docs/api/errors).

## 3. Tool aufrufen

Ein Tool ist eine Fähigkeit des Assistenten: den Korpus lesen, live suchen, schreiben, handeln. Dieses Beispiel liest die Erfassungsvolumen der letzten 7 Tage:

```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()
```

Die Antwort enthält den Namen des Tools und seine Ausgabe (hier gekürzt):

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

Die 92 aufrufbaren Tools, ihre Scopes und ihre Eingaben stehen im [Katalog](/de/docs/api/tools#katalog).

## 4. Agent befragen

Ein Agent verkettet mehrere Tools und antwortet in natürlicher Sprache. Der Schlüssel braucht den Scope `agents` sowie die Scopes der Tools, die der Agent nutzen darf.

```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()
```

Antwort, gekürzt:

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

Mehr unter [Agenten](/de/docs/api/agents).

## 5. MCP-Client verbinden

Mit Claude Code:

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

Weitere Clients behandelt der [MCP-Server](/de/docs/api/mcp).

## Noch nicht verfügbar

- **Webhooks.** Es wird nichts an Ihre Systeme gesendet. Um zu verfolgen, was neu eintrifft, rufen Sie `getSignals` oder `searchItems` in regelmäßigen Abständen ab.
- **Offizielle SDKs.** Das [OpenAPI-Dokument](https://piqline.com/api/v1/openapi.json) beschreibt jede Route: Ein Client-Generator macht daraus ein SDK in Ihrer Sprache.
- **OAuth-Anmeldung.** Es werden nur Schlüssel akzeptiert. Konnektoren, die OAuth verlangen, etwa die von claude.ai und ChatGPT, können sich noch nicht verbinden.
- **Massenexport.** Tools liefern begrenzte Ergebnisseiten (höchstens 40 Items bei `searchItems`).
