クイックスタート
サインインしてテストプロジェクトを作成し、必要なスコープだけのキーを作成します。GET /v1/tools を呼び出して一つのサービスを設定し、受け入れテスト後に別の live キーを作成します。
export GALON_API_BASE="https://api.galon.ai"
export GALON_API_KEY="gln_test_..."
curl "$GALON_API_BASE/v1/tools" -H "Authorization: Bearer $GALON_API_KEY"
認証と分離
API キーを Authorization: Bearer ヘッダーで送信します。各キーは一つの tenant、プロジェクト、環境に結び付いています。サーバー側のシークレット管理にのみ保存し、ブラウザー、モバイルアプリ、ソースリポジトリには置かないでください。
サービス単位で制限されたキー
mail:send、domain:lookup、build:create など正確なスコープだけを付与します。アプリごとに一つのキーを使います。全操作が本当に必要な場合以外はサービスのワイルドカードを避け、未使用のキーは直ちに失効させます。
mail:send
domain:lookup
domain:read
build:create
build:read
artifact:read
job:read
非同期ジョブと冪等性
変更操作は job を返します。安定した Idempotency-Key を送信してください。同じキーと意図は同じ job を返し、同じキーで意図が異なる場合は HTTP 409 になります。job を確認し、安全または冪等な要求だけを再試行します。
POST /v1/jobs
GET /v1/jobs/{job_id}
POST /v1/jobs/{job_id}/cancel
GET /v1/builds/{job_id}/artifacts
メールの送信
POST /v1/emails は from_email、subject、text または html、そして to(1 つのアドレスまたはリスト)を受け取ります。cc と bcc は任意のリストです。to、cc、bcc を合わせて異なる宛先は最大 50 件で、各宛先はクォータと課金対象の利用量に計上されます。各宛先には専用のワンクリック配信停止リンク付きの個別のコピーが届くため、bcc の宛先が開示されることはありません。抑制された宛先(バウンス、苦情、配信停止)はスキップされます。attachments は filename、content(base64)、任意の content_type を持つ最大 10 個のオブジェクトのリストです。エンコード後のメッセージは 25 MB 未満である必要があり、実行可能ファイルは拒否されます。scheduled_at(タイムゾーン付き ISO 8601、最大 72 時間先)で送信を遅らせられ、キューにある間は POST /v1/emails/{job_id}/cancel で取り消せます。POST /v1/emails/batch は添付ファイルなしの 1~100 件のメッセージを含む {"emails": [...]} を受け取ります。各メッセージは独立した job となり、バッチの Idempotency-Key と位置によって冪等です。単一の宛先には引き続き to_email を使用できます。 原子的なのはバッチ登録だけです(atomic=true)。実行と配信は独立しています。再試行にはまったく同じ順序付きリストが必要で、内容、件数、順序の変更は HTTP 409 を返します。
POST /v1/emails
POST /v1/emails/batch
POST /v1/emails/{job_id}/cancel
エラー
HTTP 401 は無効または期限切れの認証情報、403 はスコープ不足、409 は冪等性またはバージョンの競合、422 は無効な要求、503 は一時的な利用不能として扱います。
機械可読リファレンス
スキーマには OpenAPI 契約、エージェントの指示には LLM 統合ガイドを使用します。英語が正本で、パス、フィールド、スコープ、例はすべての翻訳で同一です。