本文へ移動

開発者向け

API・Webhook・MCP

アカウントのテーマと該当文書は、認証付きのJSON APIで取得できるほか、新しい該当文書をWebhookで受け取ったり、MCP対応のエージェントから照会したりできます。いずれもダッシュボードと同じく、ご契約内容と情報源の利用条件に従い、現時点でアカウントが閲覧できる内容だけを返します。

API、MCP、Webhookのご利用には、利用規約が適用されます。

curlcurl -H "Authorization: Bearer $SIGNALS_API_KEY" \ "https://signals.tokyobrief.com/api/v2/matches?limit=1&locale=ja"

APIキー

APIキーはダッシュボードの開発者向けページで作成します。キー全体が表示されるのは作成時の一度だけで、当社はハッシュ値のみを保存します。

1つのアカウントで有効にできるキーは10件までです。キーは作成したメンバーの権限で読み取り、無効化した場合やそのメンバーがアカウントを離れた場合は使えなくなります。

開発者向けページを開く

すべてのリクエストでキーを送信してください。

headerAuthorization: Bearer tbs_…

REST API

GET /api/v2/topics

アカウントのテーマ一覧。locale(既定はen、またはja)を指定できます。テンプレートから作ったテーマは、その言語の名前で返します。

200{ "data": [ { "id": "00000000-0000-4000-8000-000000000001", "title": "Battery materials subsidies", "status": "active" } ] }

GET /api/v2/matches

アカウントの該当文書を新しい順に1ページ分。

クエリパラメータ

パラメータ説明
topicIdこのテーマの該当文書だけを返します。/api/v2/topicsのidを指定します。
cursor前のページのnextCursor。cursorはtopicIdにひもづくため、同じtopicIdを指定してください。最後のページではnextCursorはnullです。
limit1ページの件数。1〜50、既定値は20。
localeen(既定)またはja。copyと情報源区分の表示言語です。

該当文書の項目

フィールド説明
id該当文書のID。
topic該当したテーマのidとtitle。
family公的情報源の種類を示す公開カテゴリ。ない場合はnull。
officialUrl公式の掲載ページ。ない場合はnull。
sourcePublishedAt情報源での公表日時(判明している場合)。
decidedAtテーマに該当した日時。
copy要約。この該当文書についてアカウントが利用できる要約がない場合はnullです(公式リンクのみ許可される情報源があるほか、要約を準備中の場合もあります)。要約は常に指定した言語で返します。英語で取得した場合、copy.excerptTranslationsに、日本語の抜粋に対する当社の英訳が入ります。
copy.documentContext文書全体についての1〜3文の説明。ない場合はnullです。長い文書で冒頭部分のみを対象とする場合、truncatedはtrueになります。

例

curlcurl -H "Authorization: Bearer $SIGNALS_API_KEY" \ "https://signals.tokyobrief.com/api/v2/matches?limit=1&locale=ja"
200{ "data": [ { "id": "00000000-0000-4000-8000-000000000002", "topic": { "id": "00000000-0000-4000-8000-000000000001", "title": "Battery materials subsidies" }, "family": { "id": "grants-industrial-projects", "label": "Grants and industrial projects" }, "officialUrl": "https://www.example.jp/news/notice.html", "sourcePublishedAt": "2026-10-01T01:00:00.000Z", "decidedAt": "2026-10-01T01:04:12.345Z", "copy": { "requestedLocale": "en", "actualLocale": "en", "headline": "New subsidy round opens for battery materials plants", "oneLineSummary": "Applications open for a subsidy round covering battery materials capacity.", "whatHappened": "A new subsidy round for battery materials plants opened for applications.", "whyItMatters": null, "dataPoints": [], "sourceExcerpts": [], "excerptTranslations": [ { "language": "en", "text": "Applications are accepted until 13 November 2026." } ], "deadline": null, "documentContext": { "text": "A ministry notice opening a subsidy round, with eligibility rules and the application schedule.", "truncated": false } } } ], "nextCursor": "eyJ2IjoxLCJh…" }

エラーと上限

ステータス説明
400クエリの値が不正です。fieldに項目名(topicId、cursor、limit、locale)が入ります。
401キーがない、不明、または無効化されています。
404APIを利用できません。
429リクエストが多すぎます。Retry-Afterヘッダーの秒数が経過してから再試行してください。
400{ "error": "invalid_request", "field": "limit" }

リクエストは1アカウントにつき毎分60件までです。この上限はアカウントのすべてのキー、およびAPIとMCPで共有されます。

Webhook

エンドポイントには、テーマの新しい該当文書が確定し次第届きます。送信済みの該当文書が情報源で訂正または取り下げられた場合は、その通知も届きます。

エンドポイントは開発者向けページで追加します。標準ポートの公開https URL、アカウントのテーマ1件、イベントの言語を指定してください。署名シークレット(whsec_…)が表示されるのは一度だけです。

1つのアカウントで有効にできるエンドポイントは10件までです。エンドポイントは作成したメンバーの権限で送信し、無効化した場合やそのメンバーがアカウントを離れた場合は送信されなくなります。無効化したエンドポイントは元に戻せません。シークレットを切り替えるには、新しいエンドポイントを追加してから古いものを無効化してください。

イベント

各イベントは、id、type、occurredAt、dataを含むJSONのPOSTです。

種類説明
signal.matcheddataはAPIと同じ該当文書です。最初の送信時にはcopyが通常nullのため、要約は後からAPIで取得してください。
signal.corrected以前の該当文書(data.matchId)が情報源で訂正されました。取得し直してください。
signal.retracted以前の該当文書(data.matchId)が情報源で取り下げられました。保存済みの内容は取り下げられたものとして扱ってください。
signal.matched{ "id": "00000000-0000-4000-8000-000000000003", "type": "signal.matched", "occurredAt": "2026-10-01T01:04:12.345Z", "data": { "id": "00000000-0000-4000-8000-000000000002", "topic": { "id": "00000000-0000-4000-8000-000000000001", "title": "Battery materials subsidies" }, "family": { "id": "grants-industrial-projects", "label": "Grants and industrial projects" }, "officialUrl": "https://www.example.jp/news/notice.html", "sourcePublishedAt": "2026-10-01T01:00:00.000Z", "decidedAt": "2026-10-01T01:04:12.345Z", "copy": null } }
signal.retracted{ "id": "00000000-0000-4000-8000-000000000004", "type": "signal.retracted", "occurredAt": "2026-10-02T03:00:00.000Z", "data": { "id": "00000000-0000-4000-8000-000000000005", "matchId": "00000000-0000-4000-8000-000000000002", "topic": { "id": "00000000-0000-4000-8000-000000000001" }, "status": "retracted", "eventAt": "2026-10-02T03:00:00.000Z" } }

署名

Signals-Signatureは t=<UNIX秒>,v1=<t、ピリオド、受信した本文そのものを連結した文字列の、エンドポイントのシークレットを鍵とするHMAC-SHA256(16進数)> です。送信のたびに署名し直します。Signals-Event-Idにはイベントのidが入ります。

headersSignals-Event-Id: 00000000-0000-4000-8000-000000000003 Signals-Signature: t=1790000000,v1=5f2b…

解析前の本文そのものを検証し、定数時間で比較してください。tが5分を超えてずれている場合は拒否してください。

nodeimport { createHmac, timingSafeEqual } from "node:crypto"; // rawBody: the request body exactly as received, before JSON.parse. export function verifySignalsWebhook(rawBody, signatureHeader, secret) { const fields = Object.fromEntries(signatureHeader.split(",").map((field) => field.split("="))); const age = Math.abs(Date.now() / 1000 - Number(fields.t)); if (!Number.isFinite(age) || age > 300) return false; const expected = createHmac("sha256", secret).update(`${fields.t}.${rawBody}`).digest(); const given = Buffer.from(fields.v1 ?? "", "hex"); return given.length === expected.length && timingSafeEqual(given, expected); }

配信と再試行

10秒以内に2xxのステータスを返してください。リダイレクトはたどりません。

配信は「少なくとも1回」です。応答が失われた場合やタイムアウトした場合は、同じidで同じイベントを再送するため、処理済みのidは無視してください。

それ以外の応答やタイムアウトは、合計8回まで、1分、5分、30分、2時間、6時間、12時間、24時間の間隔で再試行します。最後の試行も失敗した場合、そのイベントは失敗として扱われ、再送されません。

送信時点で該当文書がアカウントで利用できなくなっている場合(テーマの一時停止、ご契約の終了、情報源の利用条件の変更など)や、エンドポイントが無効化されている場合、イベントは送信されません。プライベートネットワークのアドレスに解決されるURLへの送信は、再試行せずに失敗となります。

MCP

Streamable HTTPに対応したMCPクライアントを次のエンドポイントに接続し、同じAPIキーをAuthorizationヘッダーで送信してください。

json{ "mcpServers": { "tokyo-brief-signals": { "type": "http", "url": "https://signals.tokyobrief.com/mcp", "headers": { "Authorization": "Bearer tbs_…" } } } }
ツール内容
list_topicslocaleは上記と同じです。GET /api/v2/topicsと同じ結果を返します。
list_matchestopicId、cursor、limit(数値)、localeは上記と同じです。GET /api/v2/matchesと同じ結果を返します。

引数が不正な場合はJSON-RPCエラー-32602を返し、原因が1つの項目にある場合はdata.fieldにその項目名が入ります。キー、利用可否、リクエスト上限による拒否は、APIと同じHTTP 401、404、429です。このサイト以外のOriginヘッダーを含むリクエストは403、このサーバーが対応していないMCP-Protocol-Versionヘッダーは400で拒否されます。

MCPは読み取り専用のプル型です。読み取りによってメールやWebhookが送信されることはありません。