# API-Quickstart

> Rufe den persönlichen App-Tool-Katalog ab und führe deine erste sichere SynCore-Anfrage aus.

Quelle: https://support.unitedsynergy.com/api/quickstart/

SynCore stellt Integrationen über die **App-Tools-API** bereit. Der Katalog ist dynamisch: Du siehst ausschließlich die Apps und Aktionen, die für den Benutzer hinter deinem API-Key freigegeben sind.

> **Das brauchst du**
>
> Du benötigst die Basis-URL deiner SynCore-Instanz und einen API-Key mit dem Scope `app-tools` und einem zugeordneten Actor-User. Den Rohwert des Schlüssels erhältst du nur einmal.

## 1. Zugangsdaten als Umgebungsvariablen setzen

PowerShell:

```powershell
$SynCoreBaseUrl = 'https://syncore.example.com'
$env:SYNCORE_API_KEY = 'syn_DEIN_SCHLUESSEL'
```

Bash, z. B. unter Linux oder macOS:

```bash
export SYNCORE_BASE_URL='https://syncore.example.com'
export SYNCORE_API_KEY='syn_DEIN_SCHLUESSEL'
```

Verwende die URL ohne abschließenden Schrägstrich. Schreibe den Schlüssel nicht in Quellcode, Git-Repositories, Tickets oder Screenshots.

## 2. Deinen verfügbaren Katalog abrufen

PowerShell:

```powershell
$Headers = @{ 'X-API-KEY' = $env:SYNCORE_API_KEY }
Invoke-RestMethod `
  -Method Get `
  -Uri "$SynCoreBaseUrl/api/app-tools?includeStructure=1" `
  -Headers $Headers
```

curl:

```bash
curl --request GET \
  "$SYNCORE_BASE_URL/api/app-tools?includeStructure=1" \
  --header "X-API-KEY: $SYNCORE_API_KEY"
```

Die Antwort enthält:

- `tools`: alle für diesen Schlüssel erlaubten Aktionen mit Ein- und Ausgabeschema,
- `structure`: sichtbare Apps, Seiten, Navigation und effektive Berechtigungen,
- `rules`: verbindliche Laufzeitregeln für Auswahl, Bestätigung und Readback.

## 3. Ein lesendes Tool auswählen

Wähle für den ersten Test aus `tools[]` ein Tool mit `sideEffect: "none"`. Übernimm den `name` exakt und bilde `input` nach dem gelieferten `inputSchema`.

```json
{
  "name": "textbausteine.list_templates",
  "input": {
    "limit": 10
  }
}
```

Der Name ist nur ein Beispiel. Ist die App nicht aktiviert oder fehlen dem Actor-User die Rechte, erscheint dieses Tool gar nicht in deinem Katalog.

## 4. Tool ausführen

```powershell
$Body = @'
{
  "name": "textbausteine.list_templates",
  "input": { "limit": 10 }
}
'@

Invoke-RestMethod `
  -Method Post `
  -Uri "$SynCoreBaseUrl/api/app-tools" `
  -Headers $Headers `
  -ContentType 'application/json' `
  -Body $Body
```

Eine erfolgreiche Antwort hat immer `ok: true` und nennt das ausgeführte Tool sowie das Modul. Die Fachdaten stehen je nach Tool in `data` oder in weiteren, im `outputSchema` beschriebenen Feldern.

> **Ergebnis**
>
> Wenn der Katalog geladen wird und ein lesendes Tool `ok: true` zurückgibt, sind URL, API-Key, Scope, Actor-User und dessen Berechtigungen korrekt eingerichtet.

## Sicherheitsregeln

1. Lade vor einer Aktion immer zuerst den aktuellen Katalog mit `includeStructure=1`.
2. Rate keine IDs. Ermittle Datensätze zuerst über ein sichtbares Listen- oder Such-Tool.
3. Bei mehreren Treffern muss der Benutzer die Auswahl treffen.
4. Führe Aktionen mit `confirmationRequired: true` erst nach ausdrücklicher Bestätigung aus.
5. Prüfe Änderungen anschließend mit einem Lese- oder Listen-Tool.

Standardmäßig steht jeder ausgeführte Tool-Aufruf, auch ein fachlich gescheiterter, mit Mandant, Actor-User, Tool und Ergebnis im Audit-Log. Was sich abschalten lässt, steht unter [Sicherheit der API](https://support.unitedsynergy.com/api/sicherheit/). Abgewiesene Aufrufe (`400`, `403`, `404`) erreichen das Tool nicht. Die Aufbewahrung richtet sich nach der Audit-Einstellung des Mandanten.