Neotask API リファレンス

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

認証

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

多くのエンドポイントは複数の認証要件を組み合わせています。例えば、「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 パスパラメータは以下のいずれかの値である必要があります：

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 フォーマットに従います：

{
  "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 サポートにお問い合わせください。