はじめに

Gemlead API

GemleadがXで見つけたホットリードを、いつものツールに。REST API、署名付きWebhook、AIアシスタント向けのMCPサーバーを、ひとつのキーで使えます。

始める前に

APIとMCPサーバーは、BusinessプランとEnterpriseプランで利用でき、トライアル中も使えます。すべてのエンドポイントはhttps://gemlead.ai/api/v1の下にあり、リクエストもレスポンスもsnake_caseのフィールドを使ったJSONです。日時はすべてUTCのISO 8601形式で表します。

ベースURL

https://gemlead.ai/api/v1

APIキーを取得する

GemleadのメニューからAPIを開きます。キーを使うXアカウントを選び、名前を付けて、スコープをreadのみ、またはreadとwriteから選びます。

キーはgl_live_で始まり、表示されるのは一度だけです。すぐにシークレットマネージャーか環境変数に保存してください。キーはひとつのXアカウントに属し、そのアカウントのデータにしかアクセスできません。

ターミナル

export GEMLEAD_API_KEY="gl_live_..."

最初のリクエストを送る

アカウントを取得でキーを確認します。どのリクエストでも、キーをBearerトークンとしてAuthorizationヘッダーに含めます。

レスポンスとして、キーが属するXアカウントとそのプランが返ります。

GET/v1/account

curl https://gemlead.ai/api/v1/account \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

レスポンス200

{
  "object": "account",
  "id": "a9PzK2vRtM",
  "username": "acme",
  "name": "Acme",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1180044592/acme_400x400.jpg",
  "plan": "business"
}

ホットリードを一覧表示する

Dana AIのスコアが60以上のリードがホットリードです。hot=trueで最新のホットリードを取得し、persona、score_min、日付を加えて絞り込めます。

一覧は1ページずつ返ります。ページネーションのとおり、has_moreがtrueの間はnext_cursorをたどってください。

GET/v1/leads

curl -G https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d hot=true \
  -d limit=10

レスポンス200

{
  "object": "list",
  "data": [
    {
      "id": "msgOtJ8dvT",
      "object": "lead",
      "profile": {
        "x_user_id": "1460283925",
        "username": "jane_builds",
        "name": "Jane Doe",
        "bio": "Runs a paid trading community. Daily setups, no hype.",
        "followers_count": 12400,
        "following_count": 380,
        "location": "Austin, TX",
        "website": "https://janedoe.com",
        "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
        "verified": true,
        "url": "https://x.com/jane_builds"
      },
      "score": 86,
      "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
      "hot": true,
      "status": "scored",
      "persona": {
        "id": "lvWBPnytpS",
        "name": "Tipsters"
      },
      "campaign": null,
      "conversation_id": null,
      "locked_to": null,
      "found_at": "2026-11-05T14:02:11.482Z",
      "scored_at": "2026-11-05T14:03:40.117Z",
      "updated_at": "2026-11-05T14:03:40.117Z",
      "metadata": {}
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoiMjAyNi0xMS0wNVQxNDowMzo0MC4xMTdaIn0"
}

最初のWebhookを受信する

Webhookはイベントの発生と同時にサーバーへ届くため、ポーリングは不要です。lead.hotとreply.receivedを受け取る公開HTTPSのURLを登録し、レスポンスのsecretを保存してから、自分宛てにテストイベントを送信します。lead.createdは、ホットかどうかに関係なく、新しいリードをすべて送信します。

署名の検証のとおり、すべてのリクエストをGemlead-Signatureヘッダーで検証してください。エンドポイントはアプリのAPIからも追加できます。

POST/v1/webhook_endpoints

curl -X POST https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/gemlead",
    "events": ["lead.hot", "reply.received"],
    "description": "CRM sync",
    "filters": {
      "persona_ids": ["lvWBPnytpS"]
    }
  }'

POST/v1/webhook_endpoints/:id/test

curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/test \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

AIアシスタントを接続する

https://gemlead.ai/mcpのGemlead MCPサーバーを使うと、Claude、ChatGPT、Cursorがチャットの中でリードを検索し、会話を読み、キャンペーンを運用できます。

Claude Codeなら、キーを使ってコマンド1つで接続できます。ほかのクライアントはMCPのセットアップの手順に沿って設定してください。

Claude Code

claude mcp add --transport http gemlead https://gemlead.ai/mcp \
  --header "Authorization: Bearer $GEMLEAD_API_KEY"

次のステップ

認証キー、スコープ、安全な管理方法。リードリード一覧のすべてのフィルターと、リードオブジェクト。Webhookイベント、ペイロード、署名、再試行。MCPサーバーClaude、ChatGPT、Cursor、Claude Codeの設定方法。