開発者向け

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 として書き出したものです。管理者は発行元名とともに公開鍵を信頼済みにします。信頼済みの発行元が署名していないマニフェストは、管理者の明示的な確認が必要です。

最終更新日