インスタンス設定

これらのエンドポイントはインスタンス全体の設定を読み取り・管理します。ほとんどは インスタンス 管理者のみ です。いくつかの公開プロジェクションは、未認証の画面（ログイン・パスワード再設定の ページ）が正しく分岐するのに必要な最小限だけを公開します。シークレット（OAuth クライアント資格情報） は環境に置かれ、環境外へ出ることはありません。これらのエンドポイントは、トグルとランタイムが資格情報を 持つかどうかだけを報告します。

Email

メール配信は招待とレポートの受信トレイ通知を支えます。既定はオフで、有効化には from アドレスが必要です （そうでないと送信がすべて失敗するため）。

メール有効状態

GET /api/v1/instance/email-enabled public

公開。from アドレスは決して返さず、ブール値のみを返します。パスワード再設定の画面が、セルフサービスの 復旧を提供するか、管理者に連絡するよう伝えるかを選べるようにするためです。

{ "enabled": true }

メール設定の取得

GET /api/v1/instance/email scope: admin

インスタンス管理者のみ。メール設定の全体を返します。

curl

curl "https://<your-instance>/api/v1/instance/email" \
  -H "Authorization: Bearer spantail_pat_yourtoken"

Response

{
  "emailEnabled": true,
  "emailFromAddress": "noreply@example.com",
  "emailFromName": "Spantail"
}

メール設定の更新

PATCH /api/v1/instance/email scope: admin

インスタンス管理者のみ。省略された from* フィールドは現在の値を保持します。from アドレス（現在値 または指定値）なしで配信を有効化すると 400 を返します。

リクエストボディ

Field	Type	必須	説明
emailEnabled	boolean	はい	配信のオン／オフを切り替える。
emailFromAddress	string | null	いいえ	送信元アドレス。有効化時は（現在値または指定値が）必須。
emailFromName	string | null	いいえ	送信元の表示名（100 文字以下）。

curl -X PATCH "https://<your-instance>/api/v1/instance/email" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{ "emailEnabled": true, "emailFromAddress": "noreply@example.com", "emailFromName": "Spantail" }'

Agents

AI エージェント活動機能がオンかどうか。データ量が増えうるため、既定はオフです。

エージェント有効状態

GET /api/v1/instance/agents-enabled public

エージェント UI をゲートするために任意の呼び出し元が読みます。ブール値のみを報告します。

{ "enabled": false }

エージェントの更新

PATCH /api/v1/instance/agents scope: admin

インスタンス管理者のみ。機能を切り替えます。

リクエストボディ

Field	Type	必須	説明
agentsEnabled	boolean	はい	AI エージェント活動機能のオン／オフを切り替える。

curl

curl -X PATCH "https://<your-instance>/api/v1/instance/agents" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{ "agentsEnabled": true }'

Response

{ "enabled": true }

Realtime updates

リアルタイム SSE 更新がオンかどうか。開いているストリームごとにユーザー単位の Durable Object が 常駐し、Workers Free プランの 1 日の実行時間クォータを使い切ることがあるため、既定はオフです。

リアルタイム有効状態

GET /api/v1/instance/realtime-enabled public

クライアントがストリームを開くかどうかを判断するために任意の呼び出し元が読みます。ブール値のみを 報告します。

{ "enabled": false }

リアルタイムの更新

PATCH /api/v1/instance/realtime scope: admin

インスタンス管理者のみ。機能を切り替えます。

リクエストボディ

Field	Type	必須	説明
realtimeEnabled	boolean	はい	リアルタイム SSE 更新のオン／オフを切り替える。

curl

curl -X PATCH "https://<your-instance>/api/v1/instance/realtime" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{ "realtimeEnabled": true }'

Response

{ "enabled": true }

Social login

Google と GitHub のサインイン。プロバイダは、そのクライアント ID とシークレットが環境に設定されて いるときのみ有効化できます。未設定のプロバイダを有効化すると 400 を返します。

認証プロバイダ

GET /api/v1/instance/auth-providers public

公開。ログイン画面にどのソーシャルボタンを表示するかを伝えます。プロバイダが true になるのは、 管理者が有効化し かつ ランタイムが資格情報を持つときだけです。selfSignupAvailable が true に なるのは、インスタンスがまだクレームされていない（ユーザーが 0 人）ときだけで、ログイン画面が最初の スーパー管理者をブートストラップする一度きりのサインアップフォームを提供します。

curl

curl "https://<your-instance>/api/v1/instance/auth-providers"

Response

{
  "google": true,
  "github": false,
  "selfSignupAvailable": false
}

OAuth 設定の取得

GET /api/v1/instance/oauth scope: admin

インスタンス管理者のみ。各プロバイダの有効トグルと、ランタイムが資格情報を持つか（configured）、 さらに Google のドメイン許可リストを報告します。シークレットは環境外へ出ません。

curl

curl "https://<your-instance>/api/v1/instance/oauth" \
  -H "Authorization: Bearer spantail_pat_yourtoken"

Response

{
  "google": { "enabled": true, "configured": true },
  "github": { "enabled": false, "configured": false },
  "googleAllowedDomains": ["example.com"]
}

OAuth 設定の更新

PATCH /api/v1/instance/oauth scope: admin

インスタンス管理者のみ。省略されたフィールドは現在の値を保持します。資格情報が設定されていない プロバイダを有効化すると 400 を返します。

リクエストボディ

Field	Type	必須	説明
googleOAuthEnabled	boolean	いいえ	Google サインインを有効化・無効化。
githubOAuthEnabled	boolean	いいえ	GitHub サインインを有効化・無効化。
googleAllowedDomains	string[]	いいえ	招待なしで Google サインインから自己参加できる Google Workspace ドメイン（100 件以下）。空 = 全員に招待が必要。

ノート

googleAllowedDomains のドメインは、一致する Google ユーザーが招待なしで自己参加（自動プロビジョニング） できるようにします。一致は @ の後ろの完全一致で、サブドメインは暗黙には許可されません。ドメイン外の Google ユーザーも招待で参加できます。

curl -X PATCH "https://<your-instance>/api/v1/instance/oauth" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{ "googleOAuthEnabled": true, "googleAllowedDomains": ["example.com"] }'

バージョン

バージョンの状態

GET /api/v1/instance/version 要認証

管理者に限らず、サインイン済みの任意のメンバーが利用できます。インスタンスの稼働バージョンと、 より新しいアップストリームリリースがあるかどうかを返します — System ページの更新通知の裏側の データです。稼働バージョンは秘密ではありません。認証が必要なのは、この処理が外部への更新 チェックを行うため、オープンなプロキシにしないためです。ベストエフォートでキャッシュされ、 チェックに失敗すると latest は null になります。

curl

curl "https://<your-instance>/api/v1/instance/version" \
  -H "Authorization: Bearer spantail_pat_yourtoken"

Response

{
  "current": "v0.5.1",
  "latest": "v0.6.0",
  "updateAvailable": true
}