> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squadvault.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Einführung

> Überblick über die SquadVault Public API für Skripte, Bots und externe Tools.

Mit der Public API liest und schreibst du SquadVault-Daten einer Organisation über API-Keys. Nutze sie für Skripte, Bots, Discord-Tooling und interne Integrationen.

## Basis-URL

```bash theme={null}
https://api.squadvault.xyz/v1
```

Alle Public-API-Endpunkte liegen unter `/v1`. Organisations-API-Keys funktionieren nur auf diesem versionierten Pfad. App-Proxy-Pfade ohne `/v1` gehören zum SquadVault-Dashboard (Session-Auth) und sind nicht der Integrations-Contract.

Produktive Integrationen sollten immer `https://api.squadvault.xyz/v1` verwenden.

## Was du tun kannst

| Bereich            | Operationen                                                            |
| ------------------ | ---------------------------------------------------------------------- |
| Teams              | Auflisten, abrufen, erstellen, aktualisieren, löschen                  |
| Spieler            | Auflisten, abrufen, erstellen, aktualisieren, löschen                  |
| Dokumente          | Auflisten, Download-URL, erstellen, aktualisieren, löschen             |
| Tryout-Bewerbungen | Auflisten, abrufen, Status/Notizen aktualisieren, in Spieler umwandeln |
| Uploads            | Presigned URL für Dokumentdateien anfordern                            |

Kalender, Aufgaben, Verfügbarkeit und die Discord-Verwaltung sind noch nicht Teil dieser Public API.

## Organisations-ID

Der API-Key ist auf eine Organisation beschränkt, die meisten Operationen verlangen trotzdem die ID dieser Organisation. Sie muss zum Key passen. Fehlende oder abweichende IDs führen zu `400 invalidRequest` oder `403 forbidden`.

| Wo        | Endpunkte                                                                                                                                                                                     |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pfad      | `GET /teams/{organizationId}`, `GET /teams/{organizationId}/{teamId}`, `GET /players/{organizationId}`, `GET /players/{organizationId}/{playerId}`, `GET /documents/{organizationId}`         |
| Query     | `GET /tryout-applications`, `GET /tryout-applications/{applicationId}`                                                                                                                        |
| JSON-Body | `POST /teams`, `POST /players`, `POST /documents`, `POST /uploads/document-file`, `PATCH /tryout-applications/{applicationId}`, `POST /tryout-applications/{applicationId}/convert-to-player` |

Team-, Spieler- und Dokument-**Update/Delete/Download** leiten die Organisation aus der Resource-ID ab. Tryout-**Get**, **-Update** und **-Convert** tun das nicht — `organizationId` immer mitschicken.

## Voraussetzungen

1. Eine Organisation in einem Tarif, der API-Zugriff enthält.
2. Ein Organisations-API-Key aus **Integrationen → API-Keys**.
3. Berechtigungen auf dem Key, die zu den aufgerufenen Endpunkten passen.

## Kurzes Beispiel

```bash theme={null}
curl -X GET "https://api.squadvault.xyz/v1/teams/YOUR_ORG_ID" \
  -H "x-api-key: sv_org_your_api_key"
```

## Weiter

<Columns cols={2}>
  <Card title="Authentifizierung" icon="key" href="/de/api/authentication">
    Organisations-API-Keys bei jeder Anfrage mitsenden.
  </Card>

  <Card title="Berechtigungen" icon="shield" href="/de/api/permissions">
    Key-Berechtigungen zu jedem Endpunkt passend setzen.
  </Card>
</Columns>