# Skillsail APIドキュメント

Skillsail APIドキュメント：OpenAPIの記述、構造化されたAPIエラー、バージョン管理、およびエージェントとHTTPクライアントに関する非推奨ポリシー。

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

## 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 開発者向けリソース](/ja/docs/developers)および[Skillsail 認証手順](https://skillsail.com/auth.md)。

## バージョン管理

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

MCPエンドポイントは、`/mcp` のままです。MCPクライアントは、RESTパスのプレフィックスからではなく、[Skillsail](https://skillsail.com/.well-known/mcp.json)MCPサーバーカードからプロトコルバージョンを読み取る必要があります。

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

## 構造化されたAPIエラー

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

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

例：

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

```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 開発者向けリソース](/ja/docs/developers)
- [Skillsail MCPサーバー](/ja/docs/mcp/overview)
- [OpenAPIドキュメント](https://skillsail.com/openapi.json)