API と MCP

認証

アカウント設定でキーを発行し、Authorization ヘッダーで送信してください。キーは作成時に一度だけ表示されます。キーは資格情報であり、権限そのものではありません。プランが終了すればキーも無効になります。

curl https://hashike.io/api/v1/opportunities?status=open&limit=5 \
  -H "Authorization: Bearer hsk_live_..."

エンドポイント

利用量の計上

計上の単位はリクエスト数ではなく、返却されたレコード数です。個別の元データを含まない集計レスポンスは「分析」1件として計上します。個別レコードを含む場合は、1分析に加えて、その件数をレコードとして計上します（research_brief の includeSampleAwards など）。

"usage": { "records": 0, "analyses": 1 }   // an aggregate
"usage": { "records": 21, "analyses": 0 }  // a profile with 20 awards
"usage": { "records": 5, "analyses": 1 }   // a research brief with 5 sample awards

GET /api/v1/usage — current allowance. Never metered.

上限

• フリー: 月間上限: 月 200 レコード・4 分析。通常の上限: 5 リクエスト/分。分析の上限: 1 分析リクエスト/分
• リサーチ: 月間上限: 月 1,000 レコード・20 分析。通常の上限: 20 リクエスト/分。分析の上限: 4 分析リクエスト/分
• インテリジェンス: 月間上限: 月 4,000 レコード・80 分析。通常の上限: 60 リクエスト/分。分析の上限: 12 分析リクエスト/分

上限は、メールドメインでひもづく同一組織内で、現在 API アクセスを付与している購読行の合計です。毎月1日（UTC）にリセットされます。追加の API キーを作成しても増えません。現在 API アクセスを付与している行がないアカウントには、フリーの上限が適用されます。

「データがない」と「集計していない」は別です

該当するブリーフが未作成の場合、空のオブジェクトではなく status: unavailable と reason を返します。空のレスポンスは「市場が存在しない」と誤読されるためです。

{
  "status": "unavailable",
  "reason": "no_precomputed_brief",
  "message": "No research brief has been computed for this scope...",
  "scope": { "naics": "336611" },
  "usage": { "records": 0, "analyses": 0 }
}

レスポンスの構造

各ツールは自身の出力に対応する JSON Schema（outputSchema）を公開しています。MCP の tools/list はこれを inputSchema と並べて返し、tools/call は従来どおりのテキストに加えて structuredContent としても同じ内容を返すため、クライアントはテキストからの JSON 抽出を避けられます。result の中身はツールごとに異なりますが、status・scope・provenance・usage の形はすべてのツールで共通です。

エラー

MCP

同じツール群を Model Context Protocol でも提供しています。お使いの AI クライアントに下記のエンドポイントを設定すると、自社の資料と並べて Hashike のリサーチを参照できます。上限と利用量の計上は API と共通です。

https://hashike.io/api/mcp

Transport : JSON-RPC 2.0 over POST
Auth      : Authorization: Bearer hsk_live_...
Methods   : initialize · tools/list · tools/call · ping

認証は OAuth に対応しています。MCP クライアントは動的クライアント登録を行い、ブラウザでの同意画面を経てアクセストークンを取得します。API キーを手作業で貼り付ける必要はなく、権限はご自身のアカウントに紐づきます。API キー（Bearer トークン）も引き続き利用できますので、OAuth に未対応のクライアントはそちらをお使いください。

Tool results arrive as JSON with their provenance attached, and each carries your remaining allowance so an agent can pace itself. A result with status: "unavailable" is not an error — it means that scope has not been computed or is outside coverage.

ウェブフック

現在開発中の機能です。有効化されるまで、アカウント設定にエンドポイント登録欄は表示されません。以下は有効化後の仕様です。

対応イベント： opportunity.created / opportunity.updated / award.created

{
  "id": "opportunity:ABC123:9f2c...",   // dedupe identity — key your idempotency on this
  "eventId": 48213,
  "type": "opportunity.updated",
  "entityType": "opportunity",
  "entityId": "ABC123",
  "data": { "opportunityId": "ABC123", "title": "...", "responseDeadline": "2026-11-01" },
  "ts": "2026-09-20T04:31:00.000Z"
}

配信は少なくとも1回（at-least-once）保証です。同じイベントが複数回届くことがあるため、受信側は payload.id（重複排除キー）で冪等に処理してください。

再試行

配信に失敗すると指数バックオフで再試行します：1分・5分・30分・2時間・6時間・12時間・24時間。最大試行回数に達した配信は失敗として記録され、それ以降は再試行しません。

署名の検証

各リクエストに X-Hashike-Signature と X-Hashike-Timestamp ヘッダーが付与されます。署名鍵は、作成時に一度だけ表示されるシークレットを SHA-256 でハッシュ化した値です。そのハッシュを鍵として `<timestamp>.<raw body>` の HMAC-SHA256 を計算し、ヘッダーの値と定数時間で比較してください。タイムスタンプが現在時刻から大きく離れている場合はリプレイとして拒否してください。

const crypto = require("node:crypto");

function verify(secret, timestamp, rawBody, signatureHeader) {
  const signingKey = crypto.createHash("sha256").update(secret).digest("hex");
  const expected = crypto
    .createHmac("sha256", signingKey)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signatureHeader, "utf8");
  const signatureOk = a.length === b.length && crypto.timingSafeEqual(a, b);

  const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
  return signatureOk && ageSeconds <= 300; // reject anything older than 5 minutes
}