# OpenAPI・APIカタログ (/api-reference/openapi)

> 配信APIのOpenAPI 3.1定義とAPIカタログのURL、ツールへの読み込み方法。

配信APIのHTTP仕様を機械で読めるOpenAPIとして公開しています。APIカタログからは、その定義やドキュメントの参照先を取得できます。どちらもAPIキーなしで読み取れます。

## 公開URL [#公開url]

| URL | 内容 |
| --- | --- |
| `https://api.genko.me/openapi.json` | OpenAPI 3.1.0形式の配信API定義 |
| `https://genko.me/.well-known/api-catalog` | RFC 9727に沿ったAPIカタログ |

OpenAPIはエンドポイント、認証ヘッダー、クエリ、レスポンス、エラーを記述します。APIカタログはAPIの参照先を探すための一覧です。

## ツールへ読み込む [#ツールへ読み込む]

OpenAPI 3.1に対応したAPIクライアントやコード生成ツールのインポート機能に、`https://api.genko.me/openapi.json`を指定します。ファイルから読み込むツールでは、先にJSONを保存してください。

```bash
curl --fail 'https://api.genko.me/openapi.json' -o genko-openapi.json
```

定義内のサーバーURLは`https://api.genko.me/v1`です。リクエストするときは、`workspace`にワークスペースID（スラッグ）、`endpoint`にAPIのエンドポイントを指定します。認証設定は`ApiKeyHeader`で、送信するヘッダー名は`X-API-KEY`です。

**定義の取得に認証は不要ですが、コンテンツやスキーマの取得にはAPIキーが必要です。** キーの有効期間と対象APIは[APIキーの管理](/studio/api-keys)で確認してください。

## ワークスペースのスキーマとの違い [#ワークスペースのスキーマとの違い]

公開OpenAPIは、すべてのワークスペースに共通するHTTP仕様です。各利用者が作成したAPI名やフィールド定義、記事本文、APIキーは含みません。

コンテンツのユーザー定義フィールドは任意のキーとして扱い、一覧とオブジェクト形式の応答は同じパスに記述されています。OpenAPIから生成した型だけでは、自分の`blog`に`title`や`body`があることまでは表せません。

ワークスペース固有の定義は認証付きの`/v1/{workspace}/_schema`で取得します。TypeScriptの型付きクライアントを使う場合は[CLIのinit・pull](/sdk/cli)で生成してください。キーの対象が限定されている場合、スキーマにもその対象APIだけが含まれます。

## APIカタログを読む [#apiカタログを読む]

```bash
curl --fail 'https://genko.me/.well-known/api-catalog'
```

レスポンスは`application/linkset+json`形式で、配信APIを指す`anchor`と参照先を返します。

| キー | 参照先 |
| --- | --- |
| `anchor` | `https://api.genko.me/v1` |
| `service-desc` | OpenAPI定義 |
| `service-doc` | 配信APIドキュメント |
| `status` | `https://api.genko.me/health` |

これは製品が公開する配信APIの案内です。ワークスペース内に作成したAPIの一覧は`_schema`を使います。APIカタログへの`HEAD`でも`Link`ヘッダーにカタログの場所を返します。

実際の取得例は[配信API](/api-reference/delivery)、AIへ渡す製品資料は[Markdownで読む](/ai/llms-txt)を参照してください。