# Neotask API リファレンス

Neotask プラットフォームの完全な API リファレンスです。このドキュメントでは、利用可能なすべてのエンドポイント、認証方法、エラーハンドリング、レート制限について説明します。

---

## 認証

すべての API リクエストには、以下のいずれかの方法による認証が必要です：

- **Bearer JWT**：ヘッダー `Authorization: Bearer <token>` を渡します。トークンは以下で説明するログインエンドポイントから取得します。
- **License HMAC**：Neotask デスクトップアプリケーションで使用されるデバイスバウンド HMAC-SHA256 署名。クライアントはライセンスキーとデバイスフィンガープリントから派生したシークレットでリクエストに署名します。
- **Tenant ヘッダー**：テナントスコープのエンドポイントには `x-tenant-id: <tenantId>` を含めます。このヘッダーはリクエストが適用されるテナント（ワークスペース）を識別します。

多くのエンドポイントは複数の認証要件を組み合わせています。例えば、「Tenant + Admin」はリクエストに有効な JWT（Admin ロールを持つユーザーのもの）と `x-tenant-id` ヘッダーの両方が必要です。

---

## Auth エンドポイント

Web、iOS、デスクトッププラットフォーム全体のユーザー認証用エンドポイント。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| POST | `/api/auth/login` | メールとパスワードで認証。成功時に JWT を返します。 | なし |
| POST | `/api/auth/google` | Web 上の Google OAuth で認証。Google 認証コードを期待します。 | なし |
| POST | `/api/auth/google-ios` | iOS 上の Google OAuth で認証。iOS 固有の認証ペイロードを期待します。 | なし |
| POST | `/api/auth/google-token` | Google アクセストークンを検証し、Neotask JWT を返します。 | なし |
| POST | `/api/auth/apple` | Apple Sign-In で認証。Apple アイデンティティトークンを期待します。 | なし |
| GET | `/api/auth/me` | 認証済みユーザーのプロフィール（名前、メール、アバター、ロール）を返します。 | JWT |
| DELETE | `/api/auth/account` | 認証済みユーザーのアカウントとすべての関連データを完全に削除します。 | JWT |

---

## Dashboard Auth エンドポイント

ライセンスキーログインと二要素認証（TOTP）を含む、Neotask ダッシュボード固有の認証エンドポイント。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| POST | `/api/dashboard/auth/login` | ライセンスキーで認証。成功時に JWT を返すか、TOTP が必要であることを通知します。 | なし |
| POST | `/api/dashboard/auth/totp-login` | 二要素認証が有効な場合に TOTP コードまたはバックアップコードを提供してログインを完了します。 | なし |
| GET | `/api/dashboard/auth/me` | 認証済みダッシュボードユーザーの現在のライセンス情報と機能エンタイトルメントを返します。 | JWT |
| POST | `/api/dashboard/totp/setup` | 二要素認証を設定するための TOTP シークレットと QR コードを生成します。 | JWT |
| POST | `/api/dashboard/totp/verify` | TOTP コードを検証して、アカウントの二要素認証を確認・有効化します。 | JWT |

---

## Billing エンドポイント

Stripe と RevenueCat を通じたサブスクリプション、チェックアウトセッション、アプリ内購入の管理。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| POST | `/api/billing/checkout` | Pro プランの Stripe Checkout セッションを作成。チェックアウト URL を返します。 | Tenant + Admin |
| POST | `/api/billing/checkout/enterprise` | Enterprise プランの Stripe Checkout セッションを作成。チェックアウト URL を返します。 | Tenant + Admin |
| GET | `/api/billing/status` | テナントの現在のプラン、メッセージ数、使用制限を返します。 | Tenant + Viewer |
| POST | `/api/billing/portal` | 支払い方法と請求書を管理するための Stripe カスタマーポータルセッションを作成します。 | Tenant + Admin |
| POST | `/api/billing/agent-addon` | テナントの追加エージェントスロットアドオンを購入します。 | Tenant + Admin |
| POST | `/api/billing/webhook` | Stripe Webhook ハンドラー。Stripe 署名を検証し、サブスクリプションライフサイクルイベントを処理します。 | Stripe Signature |
| POST | `/api/billing/revenuecat-sync` | RevenueCat 経由で iOS アプリ内購入を検証し、テナントにエンタイトルメントを同期します。 | Tenant + Admin |
| POST | `/api/billing/revenuecat-webhook` | RevenueCat Webhook ハンドラー。App Store から発信されたサブスクリプションイベントを処理します。 | Bearer |

---

## Chat エンドポイント

メッセージの送受信、セッション管理、非同期ジョブ結果のポーリング。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| POST | `/api/chat/init` | 認証済みユーザーのテナント、エージェント、セッションを自動プロビジョニング。1回の呼び出しで新規ユーザーのチャット環境をブートストラップするために使用します。 | JWT |
| POST | `/api/chat/send` | エージェントにメッセージを送信。メッセージは非同期で処理され、ジョブ ID が即座に返されます。 | Tenant + Admin |
| GET | `/api/chat/jobs/:jobId` | ジョブ ID による非同期チャットジョブのステータスと結果をポーリングします。 | Tenant + Viewer |
| GET | `/api/chat/messages` | 指定されたセッションのすべてのメッセージを取得。セッション ID をクエリパラメータとして渡します。 | Tenant + Viewer |
| GET | `/api/chat/sessions` | テナントのすべてのチャットセッションをリスト表示します。 | Tenant + Viewer |
| POST | `/api/chat/sessions` | 新しいチャットセッションを作成します。 | Tenant + Admin |

---

## Agent and Activity エンドポイント

テナントに関連するエージェント、セッション、ツール、ファイル、スキル、チャネル、スケジュールジョブ、チームの閲覧。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| GET | `/api/activity/agents` | テナントに属するすべてのエージェントをリスト表示します。 | Tenant |
| GET | `/api/activity/sessions` | セッションをリスト表示。`agentId`、`status`、日付範囲のクエリパラメータによるフィルタリングをサポートします。 | Tenant |
| GET | `/api/activity/sessions/:id/entries` | 特定のセッションのすべてのエントリ（メッセージとイベント）を取得します。 | Tenant |
| GET | `/api/activity/tools` | テナントのエージェントで利用可能なすべてのツールをリスト表示します。 | Tenant |
| GET | `/api/activity/files` | テナントのエージェントに関連するすべてのファイルをリスト表示します。 | Tenant |
| GET | `/api/activity/skills` | テナントのエージェントに関連するすべてのスキルをリスト表示します。 | Tenant |
| GET | `/api/activity/channels` | テナントのエージェントに関連するすべてのチャネルをリスト表示します。 | Tenant |
| GET | `/api/activity/cron-jobs` | テナントのすべてのスケジュール（cron）ジョブをリスト表示します。 | Tenant |
| GET | `/api/activity/teams` | テナント内のすべてのチームをリスト表示します。 | Tenant |

---

## Skills エンドポイント

スキルカタログの管理、スキルのインストールと設定、カスタムスキルの公開。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| GET | `/api/skills/catalog` | スキルカタログ全体を閲覧。インストール可能なすべての公開スキルを返します。 | Tenant |
| GET | `/api/skills/list` | ユーザーが現在インストールしているスキルをリスト表示します。 | Tenant + Viewer |
| POST | `/api/skills/sync` | ファイルシステムからスキルを同期。新しいスキルファイルをデプロイした後にレジストリを更新するために使用します。 | Tenant + Admin |
| POST | `/api/skills/register` | カタログからスキルを登録（インストール）します。 | Tenant + Viewer |
| DELETE | `/api/skills/register/:skillId` | ID でスキルの登録を解除（アンインストール）します。 | Tenant + Viewer |
| POST | `/api/skills/:skillId/publish` | スキルを公開してカタログで利用可能にします。 | Tenant + Admin |
| POST | `/api/skills/:skillId/unpublish` | スキルの公開を取り消し、カタログから削除します。 | Tenant + Admin |
| GET | `/api/skills/all` | 未公開のものを含むすべてのスキルをリスト表示。スキル管理用の Admin 専用エンドポイント。 | Tenant + Admin |
| PUT | `/api/skills/:skillId/env-schema` | スキルの環境変数スキーマを定義または更新。ユーザーに表示される設定フィールドを制御します。 | Tenant + Admin |
| POST | `/api/skills/:skillId/configure` | インストールされたスキルの設定値を保存します。 | Tenant + Viewer |
| DELETE | `/api/skills/:skillId/configure` | スキルのすべての設定を削除し、デフォルトにリセットします。 | Tenant + Viewer |

---

## Channel エンドポイント

メッセージングチャネル（Slack、Discord、WhatsApp など）のリンク、設定、有効化、切断。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| GET | `/api/channels/` | すべてのチャネルとその現在のステータスをリスト表示します。 | Tenant + Viewer |
| GET | `/api/channels/:channel/status` | 特定のチャネルの詳細ステータスを取得します。 | Tenant + Viewer |
| POST | `/api/channels/:channel/link` | チャネルのリンクプロセスを開始。チャネルタイプに応じてリンク URL またはセッショントークンを返します。 | Tenant + Admin |
| GET | `/api/channels/:channel/link/wait` | チャネルリンクフローの完了をロングポーリングします。チャネルが正常にリンクされるか操作がタイムアウトすると返されます。 | Tenant + Admin |
| GET | `/api/channels/:channel/jobs/:jobId` | チャネル固有の非同期ジョブの結果を取得します。 | Tenant + Admin |
| POST | `/api/channels/:channel/enable` | リンクされたチャネルを有効にし、エージェントがそこからのメッセージの受信を開始します。 | Tenant + Admin |
| POST | `/api/channels/:channel/disable` | リンクを解除せずにチャネルを無効にします。エージェントはメッセージの受信を停止しますが、チャネル接続は保持されます。 | Tenant + Admin |
| POST | `/api/channels/:channel/disconnect` | チャネルを完全に切断し、リンクを解除します。 | Tenant + Admin |
| GET | `/api/channels/:channel/config` | チャネルの現在の設定を取得します。 | Tenant + Admin |
| POST | `/api/channels/:channel/config` | チャネルの設定を更新します。 | Tenant + Admin |

---

## Google OAuth エンドポイント

Google サービスを Neotask に接続するための Google OAuth フローの開始と管理。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| GET/POST | `/oauth/google/start` | Google OAuth フローを開始。アクセスを要求する Google サービスを指定するオプションパラメータを受け付けます。 | オプション |
| GET | `/oauth/google/services` | Neotask がサポートするすべての Google サービス定義をカテゴリ別にリスト表示します。 | なし |
| GET | `/oauth/google/callback` | OAuth コールバックハンドラー。ユーザーがアクセスを許可または拒否した後に Google がここにリダイレクトします。 | なし |
| GET | `/oauth/google/status` | 進行中の OAuth フローのステータスをポーリング。フローが保留中、完了、または失敗のいずれかを返します。 | なし |

### 利用可能な Google サービス

Neotask は4つのカテゴリにまたがる25の Google サービスへの接続をサポートしています：

| カテゴリ | サービス |
|----------|----------|
| **コア** | Gmail、Calendar、Drive、Docs、Sheets、Slides、Forms、Keep、Tasks |
| **コミュニケーション** | People/Contacts、Chat、Meet、YouTube、Photos |
| **ロケーション** | Places API、Routes/Directions、Business Profile |
| **特殊** | Classroom、Play Developer、AdSense、Google Ads |

---

## Provider Keys エンドポイント

サードパーティ API キー（LLM プロバイダー用など）の管理。キーは保存時に暗号化され、オンデマンドで解決（復号）できます。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| PUT | `/api/provider-keys/:provider` | 指定されたプロバイダーの API キーを保存または更新。キーは保存前に暗号化されます。 | HMAC + Auth |
| GET | `/api/provider-keys/` | すべての保存済みプロバイダーキーをリスト表示。キー値はマスクされます（最後の4文字のみ表示）。 | Auth |
| DELETE | `/api/provider-keys/:provider` | 指定されたプロバイダーの保存済み API キーを削除します。 | HMAC + Auth |
| GET | `/api/provider-keys/:provider/resolve` | 指定されたプロバイダーの完全な API キーを復号して返します。 | Auth |
| GET | `/api/provider-keys/mode` | 現在のキーモード（ユーザー提供 vs. プラットフォームクレジット）と残りのクレジット残高を取得します。 | Auth |

### 許可されたプロバイダー

`:provider` パスパラメータは以下のいずれかの値である必要があります：

- `anthropic`
- `openai`
- `openai-codex`
- `openrouter`
- `google-ai`

---

## Usage エンドポイント

使用量の追跡、分析のクエリ、支出の監視、予算の管理。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| POST | `/api/usage/ingest` | 使用量データレコード（トークン数、使用モデルなど）を取り込みます。 | Auth |
| GET | `/api/usage/query` | 柔軟なフィルター（日付範囲、モデル、エージェント）で使用量分析をクエリします。 | Auth |
| GET | `/api/usage/summary` | 指定期間の使用量サマリーを取得。`period` をクエリパラメータとして渡します（例：`day`、`week`、`month`）。 | Auth |
| GET | `/api/usage/analytics` | モデル別およびエージェント別の内訳を含む詳細な使用量分析を取得します。 | Auth |
| GET | `/api/usage/spending` | 指定期間の支出データを取得。`period` をクエリパラメータとして渡します。 | Auth |
| GET | `/api/usage/budget` | 予算情報（合計制限、使用量、残額）を取得します。 | Auth |
| POST | `/api/usage/cron-runs` | 使用量追跡のためにスケジュール（cron）ジョブの実行を記録します。 | Auth |
| POST | `/api/usage/budget-snapshot` | 現在の予算状態のポイントインタイムスナップショットをキャプチャします。 | Auth |

---

## Onboarding エンドポイント

モデルプロバイダーの選択と API キーの設定を含む、新規ユーザーの初期セットアップガイド。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| POST | `/api/onboarding/init` | 認証済みユーザーのオンボーディング設定を初期化。デフォルト設定を作成し、オンボーディング状態を返します。 | JWT |
| GET | `/api/onboarding/models` | 利用可能なモデルプロバイダーとそのサポートモデルをリスト表示。このエンドポイントはパブリックで認証不要です。 | なし |
| POST | `/api/onboarding/setup` | オンボーディング中にプロバイダー API キーを設定。保存前にキーを検証します。 | Tenant + Admin |
| POST | `/api/onboarding/complete` | 現在のユーザーのオンボーディングを完了としてマークします。 | Dashboard Auth |

---

## Tenant エンドポイント

テナント（ワークスペース）の作成と管理、暗号化されたシークレットの保存、セッションとジョブの直接作成。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| POST | `/api/tenants/` | 新しいテナント（ワークスペース）を作成。テナント ID とデフォルト設定を返します。 | JWT |
| GET | `/api/tenants/:tenantId` | 設定やメンバー数を含む特定のテナントの詳細を取得します。 | JWT |
| POST | `/api/tenants/secrets` | テナントに関連する暗号化されたシークレットを保存。サービス統合に使用されます。 | Tenant + Admin |
| POST | `/api/tenants/sessions` | テナント内に新しいセッションを作成します。 | Tenant + Admin |
| POST | `/api/tenants/jobs` | テナント内に新しい非同期ジョブを作成します。 | Tenant + Admin |

---

## Memory エンドポイント

エージェントのメモリ設定、ファイル、コンテンツの管理。メモリにより、エージェントはセッション間で情報を永続化できます。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| GET | `/api/memory/config` | 現在のメモリ設定（有効状態、保持ポリシー、制限）を取得します。 | Auth |
| POST | `/api/memory/config` | 保持期間やストレージ制限などのメモリ設定を更新します。 | Auth |
| GET | `/api/memory/files` | エージェントに保存されているすべてのメモリファイルをリスト表示します。 | Auth |
| GET | `/api/memory/files/:filename` | ファイル名で特定のメモリファイルの内容を取得します。 | Auth |
| DELETE | `/api/memory/files/:filename` | ファイル名で特定のメモリファイルを削除します。 | Auth |
| GET | `/api/memory/content` | 保存されたメモリコンテンツを取得します。 | Auth |
| POST | `/api/memory/content` | エージェントの新しいメモリコンテンツを保存します。 | Auth |

---

## Google Accounts エンドポイント

OAuth 経由で Neotask に接続された Google アカウントの管理。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| GET | `/api/google-accounts/` | サービススコープとステータスを含むすべての接続済み Google アカウントをリスト表示します。 | Auth |
| POST | `/api/google-accounts/:accountId/activate` | 接続済み Google アカウントをアクティベートし、エージェントがその認可されたサービスを使用できるようにします。 | Auth |
| DELETE | `/api/google-accounts/:accountId` | 接続済み Google アカウントを削除し、保存されたトークンを取り消します。 | Auth |

---

## Contact and Support エンドポイント

サポート問い合わせリクエストの送信と管理。

| メソッド | エンドポイント | 説明 | 認証 |
|--------|----------|-------------|------|
| POST | `/api/contact/` | お問い合わせフォームメッセージを送信。IP アドレスあたり15分間に5リクエストのレート制限があります。 | なし |
| GET | `/api/contacts/` | ページネーション対応ですべての問い合わせ送信をリスト表示。Admin 専用。 | Admin |
| PATCH | `/api/contacts/:id` | 問い合わせ送信のステータスを更新（例：解決済みとしてマーク）。 | Admin |
| DELETE | `/api/contacts/:id` | 問い合わせ送信を削除します。 | Admin |

---

## レート制限

Neotask はサービスの安定性を保護するために、特定のエンドポイントにレート制限を適用します。レート制限を超えると、API は `429 Too Many Requests` レスポンスを返します。

| エンドポイントカテゴリ | 制限 |
|-------------------|-------|
| お問い合わせフォーム | IP あたり15分間に5リクエスト |
| ログイン試行 | IP あたり15分間に10リクエスト |
| トラッキング/分析 | IP あたり60秒間に30リクエスト |

---

## エラーレスポンス

すべてのエラーレスポンスは一貫した JSON フォーマットに従います：

```json
{
  "error": "Error message description",
  "status": 400
}
```

### ステータスコード

| コード | 意味 |
|------|---------|
| 400 | **Bad Request** -- リクエストが不正であるか、無効なパラメータが含まれています。 |
| 401 | **Unauthorized** -- 認証がないか、提供されたトークンが無効です。 |
| 402 | **Payment Required** -- テナントのクレジットが枯渇しています。プランをアップグレードするかクレジットを追加してください。 |
| 403 | **Forbidden** -- 認証済みユーザーにこのアクションに対する十分な権限がありません。 |
| 404 | **Not Found** -- リクエストされたリソースが存在しません。 |
| 429 | **Rate Limited** -- リクエストが多すぎます。レスポンスヘッダーに示された期間の後に再試行してください。 |
| 500 | **Internal Server Error** -- サーバーで予期しないエラーが発生しました。問題が続く場合は Neotask サポートにお問い合わせください。 |