Skillsail API-Dokumentation

Die Skillsail API hat die Version 1. Die OpenAPI-Beschreibung liegt unter https://skillsail.com/openapi.json. Die Kurserstellung ist keine REST-Ressourcensammlung: Agenten erstellen und bearbeiten Module über den Skillsail-MCP-Server 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 und Skillsail-Auth-Anleitung.

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 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:

{
  "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:

{
  "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
• Skillsail-MCP-Server
• OpenAPI-Dokument