Skillsail APIドキュメント

このSkillsail APIドキュメントはバージョン1について説明しています。OpenAPIの説明はhttps://skillsail.com/openapi.json です。コースの作成はRESTリソースの集合ではありません。エージェントは、https://skillsail.com/mcpにあるSkillsail MCPサーバーを通じてモジュールを作成・編集します。

OpenAPI仕様

GET https://skillsail.com/openapi.json OpenAPI 3.1 JSONを返します。以下の内容を網羅しています：

• GET /api/health — サービスの利用可能性
• GET /openapi.json — この OpenAPI ドキュメント
• GET /.well-known/oauth-protected-resource/mcp — OAuth 保護リソースのメタデータ
• POST /mcp — 認証済み Skillsail MCP 転送

関連するドキュメント：Skillsail 開発者向けリソースおよびSkillsail 認証手順。

バージョン管理

オプションのリクエストヘッダー「Skillsail-Api-Version: 1 」を送信してください。このヘッダーが省略された場合、Skillsailはv1を提供します。OpenAPIドキュメント内の現在のinfo.version は、1.0.0 です。

MCPエンドポイントは、/mcp のままです。MCPクライアントは、RESTパスのプレフィックスからではなく、SkillsailMCPサーバーカードからプロトコルバージョンを読み取る必要があります。

Skillsailが本ドキュメントおよびOpenAPIで公開するまでは、将来の/v2 URLを想定しないでください。

構造化されたAPIエラー

RESTディスカバリーエラーには、RFC 9457（application/problem+json ）が使用されます。GET /openapi.json は、ディスカバリーが利用できない場合にこのモデルを使用します。すべての問題オブジェクトには以下が含まれます：

• type — 問題クラスを識別するURI
• title — 簡潔で安定した要約
• status — HTTPステータスコード
• detail — 人間が読みやすいメッセージ
• code — 機械可読なSkillsailエラーコード

例：

{
  "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の保護リソースメタデータ（/.well-known/oauth-protected-resource/mcp ）では、problem+jsonではなく、OAuth JSONが使用されています。設定の障害が発生すると、503 application/json が返されます：

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

/.well-known/oauth-protected-resource/mcp に未知のサフィックスが付いた場合、404 と、Not found を含む text/plain の本文が返されます。

POST /mcp にある MCP HTTP トランスポート：

• Authorization ヘッダーがない場合：401 （本文は空）およびWWW-Authenticate （resource_metadata 、error= は含めない）。Content-Type がapplication/json である場合のみ、JSONを解析してください。
• 無効または形式不備のベアラー・トークン：401 JSON{ "error": "invalid_token", "error_description": "..." }
• 権限のない有効なトークン：403 JSON{ "error": "insufficient_scope", "error_description": "..." }
• 認証サービスの停止：503 JSON{ "error": "temporarily_unavailable", "error_description": "..." } にてRetry-After

非推奨

操作や表現が非推奨となった場合、応答には以下が含まれます：

• Deprecation: @1688169599 — RFC 9745 構造化フィールド「Date」（Unix タイムスタンプ）。これはブール値の「true 」ではありません。
• Sunset HTTP日付（RFC 8594）付き

互換性を損なう変更については、サポート終了日の少なくとも90日前に告知されます。機能追加や下位互換性のある変更については、新しいバージョンを発行せずにv1に組み込まれる場合があります。サポート終了後、Skillsailは当該機能を削除する場合があります。

RESTリクエストが成功した場合、Skillsail-Api-Version: 1 のような応答が返されることがあります。

関連項目

• Skillsail 開発者向けリソース
• Skillsail MCPサーバー
• OpenAPIドキュメント