# Skillsail API-Dokumentation

Skillsail API-Dokumentation: OpenAPI-Beschreibung, typisierte Fehler, Versionierung und Abkündigungsrichtlinie für Agenten und HTTP-Clients.

Die Skillsail API hat die Version **1**. Die OpenAPI-Beschreibung liegt unter [https://skillsail.com/openapi.json](https://skillsail.com/openapi.json). Die Kurserstellung ist keine REST-Ressourcensammlung: Agenten erstellen und bearbeiten Module über den [Skillsail-MCP-Server](/de/dokumentation/mcp/ki-assistenten) unter `https://skillsail.com/mcp`.

## OpenAPI-Spezifikation

`GET https://skillsail.com/openapi.json` liefert OpenAPI-3.1-JSON. Dokumentiert sind:

- `GET /api/health` — Erreichbarkeit des Dienstes
- `GET /openapi.json` — dieses OpenAPI-Dokument
- `GET /.well-known/oauth-protected-resource/mcp` — OAuth-Protected-Resource-Metadaten
- `POST /mcp` — authentifizierter Skillsail-MCP-Transport

Weiterführende Dokumentation: [Skillsail-Entwicklerressourcen](/de/dokumentation/entwickler) und [Skillsail-Auth-Anleitung](https://skillsail.com/auth.md).

## Versionierung

Senden Sie den optionalen Request-Header `Skillsail-Api-Version: 1`. Fehlt der Header, liefert Skillsail v1. Die aktuelle `info.version` im OpenAPI-Dokument ist `1.0.0`.

Der MCP-Endpunkt bleibt `/mcp`. MCP-Clients sollen die Protokollversion aus der [Skillsail-MCP-Server-Card](https://skillsail.com/.well-known/mcp.json) lesen, nicht aus einem REST-Pfadpräfix.

Gehen Sie nicht von einer künftigen `/v2`-URL aus, bis Skillsail sie in diesem Dokument und in OpenAPI veröffentlicht.

## Typisierte Fehler

REST-Discovery-Fehler verwenden RFC 9457 `application/problem+json`. `GET /openapi.json` nutzt dieses Modell, wenn Discovery nicht verfügbar ist. Jedes Problemobjekt enthält:

- `type` — URI der Problemklasse
- `title` — kurze, stabile Zusammenfassung
- `status` — HTTP-Statuscode
- `detail` — menschenlesbare Meldung
- `code` — maschinenlesbarer Skillsail-Fehlercode

Beispiel:

```json
{
  "type": "https://skillsail.com/docs/api#not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "This URL is not a Skillsail API resource.",
  "code": "not_found"
}
```

OAuth-Protected-Resource-Metadaten (`/.well-known/oauth-protected-resource/mcp`) verwenden OAuth-JSON, nicht problem+json. Ein Konfigurationsausfall liefert `503` `application/json`:

```json
{
  "error": "temporarily_unavailable",
  "error_description": "OAuth metadata is temporarily unavailable"
}
```

Unbekannte Suffixe auf dieser Well-known-Route liefern `404` mit dem `text/plain`-Body `Not found`.

Der MCP-HTTP-Transport unter `POST /mcp`:

- Kein `Authorization`-Header: `401` mit leerem Body und `WWW-Authenticate` (`resource_metadata`, ohne `error=`). JSON nur parsen, wenn `Content-Type` `application/json` ist.
- Ungültiges oder fehlerhaftes Bearer-Token: `401` JSON `{ "error": "invalid_token", "error_description": "..." }`
- Gültiges Token ohne Berechtigung: `403` JSON `{ "error": "insufficient_scope", "error_description": "..." }`
- Ausfall des Auth-Dienstes: `503` JSON `{ "error": "temporarily_unavailable", "error_description": "..." }` mit `Retry-After`

## Abkündigung

Wenn eine Operation oder Repräsentation abgekündigt wird, enthalten Antworten:

- `Deprecation: @1688169599` — RFC-9745-Date (Unix-Zeitstempel). Das ist kein boolesches `true`.
- `Sunset` mit einem HTTP-Datum (RFC 8594)

Breaking Changes werden mindestens 90 Tage vor dem Sunset-Datum angekündigt. Additive, abwärtskompatible Änderungen können in v1 ohne neue Versionsnummer erscheinen. Nach Sunset kann Skillsail die Operation entfernen.

Erfolgreiche REST-Antworten können `Skillsail-Api-Version: 1` zurückgeben.

## Verwandte Seiten

- [Skillsail-Entwicklerressourcen](/de/dokumentation/entwickler)
- [Skillsail-MCP-Server](/de/dokumentation/mcp/ki-assistenten)
- [OpenAPI-Dokument](https://skillsail.com/openapi.json)