# Kanaeru AI 開発者ポータル

開発者、そしてAIエージェントが**Kanaeru AI**をプログラムから利用するために
必要な情報をまとめています。サインアップもAPIキーもサンドボックスの申請も不要です。
読み取り系エンドポイントは公開されており、そのまま利用できます。

| リソース | URL |
| --- | --- |
| OpenAPI 3.1 仕様（JSON） | https://www.kanaeru.ai/openapi.json |
| OpenAPI 3.1 仕様（YAML） | https://www.kanaeru.ai/openapi.yaml |
| APIインデックス | https://www.kanaeru.ai/api/v1 |
| 公式CLI（npmの `kanaeru-cli`） | https://www.npmjs.com/package/kanaeru-cli |
| エージェント向け指示 | https://www.kanaeru.ai/agent-instructions.md |
| llms.txt | https://www.kanaeru.ai/llms.txt |
| サイトマップ | https://www.kanaeru.ai/sitemap.xml |
| RSS（日本語） | https://www.kanaeru.ai/rss-ja.xml |
| サポート | support@kanaeru.ai |

## ベースURLとバージョン

```
https://www.kanaeru.ai/api/v1
```

APIはURLパスでバージョン管理しています。すべてのエンドポイントの正規プレフィックスは
`/api/v1/...` です。バージョンなしの `/api/...` パスも最新メジャーバージョンのエイリアスとして
引き続き利用できます。`v1` の中では日付ベースのリリースを行っており、現在のリリースは
`GET /api/v1/health` の `version`、OpenAPIドキュメントの `info.version`、そして**すべての**
APIレスポンスの `Kanaeru-Version` ヘッダーで確認できます。エンドポイントや任意フィールドの
追加といった後方互換のある変更は日付のみを更新し、既存の呼び出しを壊しません。
破壊的変更は必ず新しいプレフィックス（`/api/v2/...`）で提供し、`/api/v1` の提供も継続します。

### 廃止ポリシー

現在、廃止予定のものはありません。エンドポイントまたはメジャーバージョンの廃止が決まった場合は:

1. 決定した日から `Deprecation` ヘッダー（[RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)）を返し始めます。
2. `Sunset` ヘッダー（[RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)）で廃止日を通知します。
   廃止日は**最低でも180日先**に設定します。
3. スケジュールを本ページで公開します。

Sunsetの日付を過ぎるまで、廃止予定の機能は動作し続けます。`Deprecation` ヘッダーの
ないレスポンスが予告なく消えることはありません。

## 認証

**不要です。** 以下の読み取り系エンドポイントはすべて公開・認証不要です。
APIキーの管理もOAuthフローもありません。

書き込み系の2つのエンドポイント（`sendChatMessage`、`submitContactRequest`）も
認証不要です。ウェブサイトのお問い合わせフォームとチャットウィジェットが使用しているものと
同一だからです。これらは実際の担当者に届くため、「メール送信」ツールと同様に扱ってください。
ユーザーがKanaeru AIへの連絡を明示的に希望した場合にのみ呼び出し、ループ内で実行しないでください。

認証付き・大量アクセス・契約に基づくアクセスが必要な場合は support@kanaeru.ai までご連絡ください。

## クイックスタート

```bash
# 1. どのようなエンドポイントがあるか
curl -s https://www.kanaeru.ai/api/v1

# 2. 機械可読なスキーマ全体
curl -s https://www.kanaeru.ai/openapi.json

# 3. Kanaeru AIが提供するサービス一覧
curl -s "https://www.kanaeru.ai/api/v1/services?locale=ja"

# 4. 実績の確認
curl -s https://www.kanaeru.ai/api/v1/case-studies

# 5. 記事をMarkdownで読む
curl -s -H "Accept: text/markdown" https://www.kanaeru.ai/ja/blog
```

## エンドポイント

### メタ情報

| Operation | メソッドとパス | 返却内容 |
| --- | --- | --- |
| `getApiIndex` | `GET /api/v1` | 公開エンドポイントの一覧 |
| `getHealth` | `GET /api/v1/health` | 稼働状況とAPIバージョン |
| `getOpenApiDocument` | `GET /openapi.json` | 本APIのOpenAPI 3.1ドキュメント |

### カタログ（読み取り専用）

| Operation | メソッドとパス | 返却内容 |
| --- | --- | --- |
| `listServices` | `GET /api/v1/services` | 全サービス（slug、カテゴリ、正規URL付き） |
| `getService` | `GET /api/v1/services/{slug}` | 単一サービス |
| `listCaseStudies` | `GET /api/v1/case-studies` | 実績と測定された成果 |
| `getCaseStudy` | `GET /api/v1/case-studies/{slug}` | 単一の事例 |
| `listBlogPosts` | `GET /api/v1/blog-posts` | 技術記事（新しい順） |
| `getBlogPost` | `GET /api/v1/blog-posts/{slug}` | 単一記事（Markdown本文を含む） |

カタログ系エンドポイントは `?locale=en` または `?locale=ja` に対応し、一覧系は
`?limit=`（1〜100、既定50）に対応します。`listBlogPosts` は `?tag=` にも対応します。

### コンタクト（担当者に届きます）

| Operation | メソッドとパス | 動作 |
| --- | --- | --- |
| `sendChatMessage` | `POST /api/v1/chat` | メッセージを送信しスレッドIDを返却 |
| `getChatHistory` | `GET /api/v1/chat-history?sessionId=` | 既存セッションの履歴 |
| `submitContactRequest` | `POST /api/v1/send-email` | お問い合わせ・ニュースレター登録をメール送信 |

例:

```bash
curl -s -X POST https://www.kanaeru.ai/api/v1/send-email \
  -H "Content-Type: application/json" \
  -d '{
    "type": "contact",
    "name": "山田 太郎",
    "email": "taro@example.com",
    "company": "Example株式会社",
    "projectType": "固定価格MVP",
    "message": "3週間で顧客ポータルを構築したいです。"
  }'
```

## エラー形式

エラーは、すべてのエンドポイント・すべてのステータスコードにおいて、
HTMLページではなく**常にJSON**で返却されます。

```json
{
  "error": {
    "code": "invalid_request",
    "message": "sessionId is required.",
    "hint": "Pass ?sessionId=<id> as a query parameter.",
    "status": 400,
    "documentation_url": "https://www.kanaeru.ai/developers"
  }
}
```

分岐には `error.message` ではなく `error.code` を使用してください。
メッセージは人間向けであり、表現が変わる可能性があります。コードは安定しています。

| コード | ステータス | 意味 |
| --- | --- | --- |
| `invalid_request` | 400 | パラメータまたはボディの不足・不正 |
| `not_found` | 404 | 該当するエンドポイントまたはリソースがない |
| `method_not_allowed` | 405 | メソッド非対応。`Allow` ヘッダーを参照 |
| `not_acceptable` | 406 | `Accept` が `text/html` と `text/markdown` の両方を拒否 |
| `unsupported_media_type` | 415 | ボディを `application/json` で送信してください |
| `rate_limited` | 429 | `Retry-After` の間隔を空けて再試行 |
| `service_not_configured` | 503 | サーバー側で依存サービスが未設定 |
| `upstream_error` | 502 | 下流サービスの障害。バックオフして再試行 |
| `internal_error` | 500 | 予期しない障害。バックオフして再試行 |

## レート制限

クライアント（送信元IP）ごとのクォータ:

| ポリシー | エンドポイント | クォータ |
| --- | --- | --- |
| `read` | カタログ、ヘルスチェック、インデックス | 60リクエスト / 60秒 |
| `write` | `POST /api/v1/chat`、`POST /api/v1/send-email` | 10リクエスト / 60秒 |

すべてのAPIレスポンスは、標準ヘッダー
（[draft-ietf-httpapi-ratelimit-headers](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/)）で
クォータを通知します。構造化形式と広く利用されているレガシー形式の両方を返します。

```
RateLimit-Policy: "read";q=60;w=60
RateLimit: "read";r=59;t=42
RateLimit-Limit: 60
RateLimit-Remaining: 59
RateLimit-Reset: 42
```

クォータを超えると、標準のJSONエラー形式（`error.code = "rate_limited"`）と、待機秒数を示す
`Retry-After` ヘッダー付きの**429**を返します。`RateLimit-Remaining` を見て自己調整し、
`Retry-After` に従えばブロックされることはありません。書き込み系は担当者に届きます。
ユーザーの意図1件につき1メッセージとし、再試行ループを組まないでください。
より高いスループットや保証が必要な場合は support@kanaeru.ai までご連絡ください。

## Markdownコンテンツネゴシエーション

本サイトの全ページは、[acceptmarkdown.com](https://acceptmarkdown.com/) に従い、
`Accept: text/markdown` に対して同一URLのMarkdown表現を返します。
レスポンスには `Vary: Accept, Accept-Encoding` が付与されるため、CDNが誤って
HTML版を返すことはありません。

```bash
curl -s -H "Accept: text/markdown" https://www.kanaeru.ai/ja/services/rag-implementation
curl -sI -H "Accept: text/markdown" https://www.kanaeru.ai/ja | grep -i -E 'content-type|vary'
```

ページURLに `.md` を付けることもできます。各ページでは
`<link rel="alternate" type="text/markdown">` として案内しています。

```bash
curl -s https://www.kanaeru.ai/ja/blog.md
```

存在しないパスには実際の**HTTP 404**を返し、サイトマップ・llms.txt・本ページへの
リンクを含む短いMarkdown本文を添えます。迷子になったエージェントが1ホップで復帰できます。

## Function Calling

OpenAPIドキュメントは、LLMのツール定義へそのまま変換できるように記述しています。
すべてのoperationに一意の `operationId`、`summary`、説明文、型付きパラメータ、
`components/schemas` 配下のレスポンススキーマがあります。お使いのフレームワークの
OpenAPI→ツール変換機能を `https://www.kanaeru.ai/openapi.json` に向ければ、
上記のoperation IDがそのままツール名になります。

## コマンドラインツール（Kanaeru CLI）

**`kanaeru-cli`** は本APIの公式コマンドラインクライアントです。リポジトリの
[`cli/`](https://github.com/kanaerulabs/kanaeru-ai/tree/main/cli) ディレクトリで開発しており、
Node.js 18以上で動作し、ランタイム依存はゼロ、npmからインストールできます。

```bash
npm install -g kanaeru-cli

kanaeru services              # Kanaeru AIが提供する全サービス
kanaeru services rag-implementation
kanaeru case-studies          # 測定された成果付きの実績
kanaeru blog --limit 5        # 最新の技術記事
kanaeru blog <slug>           # 単一記事（Markdown本文全体）
kanaeru health                # 稼働状況と現在のAPIバージョン
kanaeru openapi               # OpenAPI 3.1ドキュメントを出力
```

すべてのコマンドは `--locale en|ja` と `--json`（スクリプト向けの生APIレスポンス）に
対応しています。CLIは上記の公開エンドポイントの薄いラッパーであり、CLIでできることは
すべて `curl` でも実行できます。

## 開発者向けツール

**Growth Kit** は、ブログ記事をX、LinkedIn、Medium、Dev.to向けのコンテンツに変換する
オープンソースのClaude Codeプラグインです。ランタイム依存なしでClaude Code内で動作します。

```
/plugin marketplace add kanaerulabs/growth-kit
```

ソース: https://github.com/kanaerulabs/growth-kit

## ステータスとサポート

独立したステータスページはありません。`GET /api/health` が稼働確認のシグナルです。
不具合、アクセス権限、上限緩和、連携のご相談などは **support@kanaeru.ai** までご連絡ください。
日本の営業日1日以内に担当者が返信します。

---

Canonical HTML: https://www.kanaeru.ai/ja/developers
Markdown of any page: send `Accept: text/markdown`, or append `.md` to the URL.
Site index for agents: https://www.kanaeru.ai/llms.txt · API: https://www.kanaeru.ai/openapi.json · Contact: support@kanaeru.ai