API クイックスタート
新しいキーから AI 同僚の返信まで、ターミナルに貼り付けられるコマンドで進めます。curl と、AI 同僚が 1 人以上いるワークスペースのグループ会話が必要です。
1. キーを作成するこのセクションへのリンクをコピー
ワークスペースで 設定 › API キー を開き、キーに名前を付け、read:profile、read:channels、write:messages の 3 つのスコープを与えます。表示されたらキーをコピーしてください。表示は一度だけです。
コマンドやファイルに書かずにシェルへ渡します。下の 1 行目はキーの貼り付けを待ち、画面には表示しません。続けてデプロイメントのアドレスを設定します。
read -rs api_key && export api_key
export workspace="https://<your-deployment>"2. キーの持ち主を確認するこのセクションへのリンクをコピー
curl -sS -H "Authorization: Bearer $api_key" \
"$workspace/api/me"キーの持ち主とそのロールが返ります。401 は、キーがない、打ち間違い、失効済み、または期限切れを意味します。
3. グループ会話を選ぶこのセクションへのリンクをコピー
ワークスペースでグループ会話を開くと、アドレスの /group/ の後ろの部分がその ID です。下の呼び出しでも会話が一覧されます。ID を変数に入れておきます。
curl -sS -H "Authorization: Bearer $api_key" \
"$workspace/api/channels?limit=20"
export channel_id="<the conversation id>"4. メッセージを送るこのセクションへのリンクをコピー
curl -sS -X POST \
-H "Authorization: Bearer $api_key" \
-H "content-type: application/json" \
-d '{"id":"quickstart-1","text":"Hello. What can you help me with?"}' \
"$workspace/api/groups/$channel_id"サーバーは 202 を返します。メッセージは受け付けられ、会話にいる AI 同僚はアプリと同じように答えます。id は自分で決める値で、同じ id を 2 回送っても 1 件のメッセージなので、再試行しても安全です。1 人の AI 同僚に宛てるには "agentId" を加えます。
5. 返信を読むこのセクションへのリンクをコピー
curl -sS -H "Authorization: Bearer $api_key" \
"$workspace/api/groups/$channel_id"会話の messages が返ります。AI 同僚の返信は agentId が設定されたメッセージです。書いている間の status は queued または running、誰かの回答が必要なときは reason 付きの waiting、その後 completed または failed になります。終わるまで同じ呼び出しを繰り返してください。
プラグインマニフェストこのセクションへのリンクをコピー
プラグインは JSON のマニフェストを 1 つ添えて配布します。バージョン 1 では、プラグイン(id、name、version、publisher)、MCP のアドレス(server.url)、Bot に提供する tools、settings のフォーム、permissions(hosts、access、読み取る data)、ライフサイクルの hooks、必要なもの(requires)を記述します。管理者は 管理 › プラグイン › プラグインマニフェスト で要求内容を確認してからインストールします。
{
"manifestVersion": 1,
"id": "ticket-desk",
"name": "Ticket desk",
"version": "1.2.0",
"publisher": "Example Ltd",
"server": { "url": "https://mcp.tickets.example/mcp" },
"tools": [{ "name": "search_tickets" }],
"settings": [{ "key": "apiKey", "label": "API key", "type": "secret", "header": "X-Desk-Key", "required": true }],
"permissions": { "hosts": ["mcp.tickets.example"], "access": "read", "data": ["Ticket titles and status"] },
"hooks": { "url": "https://mcp.tickets.example/events", "events": ["approval.decided"] },
"requires": { "apiVersion": "2026-10-15", "plugins": [] }
}アドレスはすべて https で、記載されたホスト上にある必要があります。マニフェストで宣言されていないツールは Bot に提供されず、"access": "read" なら接続は読み取り専用になります。各設定は指定したリクエストヘッダーとしてプラグインに届き、secret の設定は保管庫に保存されて再表示されません。フックは approval.requested、approval.decided、run.finished を署名付き Webhook で受け取り、署名シークレットはインストール時に一度だけ表示されます。
requires.apiVersion と requires.plugins(1.2.0、>=1.2.0、^1.2.0 などのバージョン)はインストール前に確認され、別のプラグインが必要としているプラグインは、そのプラグインをアンインストールするまで残ります。インストールしたバージョンはすべて、動作する API バージョンとともに保管され、ロールバックに使えます。
マニフェストに署名すると、検証済みとしてインストールされます。synthia plugin keygen で Ed25519 の鍵ペアを作り、synthia plugin sign manifest.json --key publisher-key.pem で署名を追加します。署名の対象は signature を除いたマニフェストで、すべてのオブジェクトのキーを並べ替え、空白を入れない JSON として書き出したものです。管理者は発行元名とともに公開鍵を信頼済みにします。信頼済みの発行元が署名していないマニフェストは、管理者の明示的な確認が必要です。
最終更新日