Skip to content

Developers

API, webhooks and MCP

Read your account's topics and matches over an authenticated JSON API, receive new matches by webhook, or let an MCP-capable agent query them. All three return only what your account may see now: the same entitlement and source-rights rules as the dashboard.

Use of the API, MCP and webhooks is governed by the Terms of Service.

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

API keys

Create a key on the developers page of your dashboard. The full key is shown once; we store only a hash.

An account can hold up to 10 active keys. A key reads as the member who created it, and stops working when it is revoked or that member leaves the account.

Open the developers page

Send the key on every request:

headerAuthorization: Bearer tbs_…

REST API

GET /api/v2/topics

Your account's topics. Optional locale, en (default) or ja: a topic made from a template is titled in that language.

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

GET /api/v2/matches

One page of your account's matches, newest first.

Query parameters

ParameterMeaning
topicIdOnly this topic's matches: an id from /api/v2/topics.
cursorThe nextCursor of the previous page. Keep the same topicId; a cursor is bound to it. nextCursor is null on the last page.
limitPage size, 1–50. Default 20.
localeen (default) or ja: the language of copy and family labels.

Match fields

FieldMeaning
idThe match id.
topicThe topic it matched: id and title.
familyThe kind of official source, as a public category, or null.
officialUrlThe official publication, or null.
sourcePublishedAtWhen the source published it, if known.
decidedAtWhen it matched your topic.
copyThe summary, or null when none is available to your account for this match (some sources permit only the official link; a summary may also still be in preparation). Copy is in the requested language; for an English request, copy.excerptTranslations holds our stored English of passages quoted in Japanese.
copy.documentContextOne to three sentences about the whole document, or null when there is none. truncated is true when it covers only the first part of a long document.

Example

curlcurl -H "Authorization: Bearer $SIGNALS_API_KEY" \ "https://signals.tokyobrief.com/api/v2/matches?limit=1&locale=en"
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…" }

Errors and limits

StatusMeaning
400A query value is invalid; field names it: topicId, cursor, limit or locale.
401The key is missing, unknown or revoked.
404API access is not available.
429Too many requests; retry after the Retry-After header's seconds.
400{ "error": "invalid_request", "field": "limit" }

Each account may make 60 requests a minute, shared by all its keys and by the API and MCP together.

Webhooks

An endpoint receives each new match on one of your topics as soon as it is accepted, and a notice if a match it was sent is later corrected or retracted at the source.

Add an endpoint on the developers page: a public https URL on the standard port, one of your topics, and the language of its events. Its signing secret (whsec_…) is shown once.

An account can have up to 10 active endpoints. An endpoint sends as the member who created it, and stops sending when it is revoked or that member leaves the account. Revoking one is permanent; to rotate a secret, add a new endpoint and then revoke the old one.

Events

Each event is a POST of JSON with id, type, occurredAt and data.

TypeMeaning
signal.matcheddata is a match, the same object the API returns. Its copy is usually null when first sent: read the match from the API later for the summary.
signal.correctedAn earlier match (data.matchId) was corrected at the source; re-read it.
signal.retractedAn earlier match (data.matchId) was retracted at the source; treat what you stored from it as withdrawn.
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" } }

Signature

Signals-Signature is t=<unix seconds>,v1=<hex HMAC-SHA256 of t, a full stop and the raw body>, keyed by the endpoint's secret; each attempt is signed afresh. Signals-Event-Id repeats the event id.

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

Verify the raw body before parsing it, compare in constant time, and reject a t more than 5 minutes away:

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); }

Delivery and retries

Answer with any 2xx status within 10 seconds. Redirects are not followed.

Delivery is at least once: after a lost acknowledgement or a timeout the same event is sent again with the same id, so ignore an id you have already processed.

Any other answer or a timeout is retried, up to 8 attempts in all, waiting 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h between them. After the last attempt the event is marked failed and not sent again.

An event is not sent if, when it is due, its match is no longer available to your account (for example the topic was paused, the plan lapsed or the source's terms changed), or the endpoint was revoked. A URL that resolves to a private network address fails without retry.

MCP

Connect any MCP client that supports Streamable HTTP to this endpoint, with the same API key in an Authorization header:

json{ "mcpServers": { "tokyo-brief-signals": { "type": "http", "url": "https://signals.tokyobrief.com/mcp", "headers": { "Authorization": "Bearer tbs_…" } } } }
ToolWhat it does
list_topicslocale, as above. The same result as GET /api/v2/topics.
list_matchestopicId, cursor, limit (a number) and locale, as above. The same result as GET /api/v2/matches.

Invalid arguments return JSON-RPC error -32602, with data.field when one field is at fault. Key, availability and rate-limit refusals are the same HTTP 401, 404 and 429 as the API. A request carrying an Origin header other than this site's is refused with 403, and an MCP-Protocol-Version header this server does not support with 400.

MCP is read-only and pull-based: reading never sends email or webhooks.