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.
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.
Send the key on every request:
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.
GET /api/v2/matches
One page of your account's matches, newest first.
Query parameters
| Parameter | Meaning |
|---|---|
| topicId | Only this topic's matches: an id from /api/v2/topics. |
| cursor | The nextCursor of the previous page. Keep the same topicId; a cursor is bound to it. nextCursor is null on the last page. |
| limit | Page size, 1–50. Default 20. |
| locale | en (default) or ja: the language of copy and family labels. |
Match fields
| Field | Meaning |
|---|---|
| id | The match id. |
| topic | The topic it matched: id and title. |
| family | The kind of official source, as a public category, or null. |
| officialUrl | The official publication, or null. |
| sourcePublishedAt | When the source published it, if known. |
| decidedAt | When it matched your topic. |
| copy | The 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.documentContext | One 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
Errors and limits
| Status | Meaning |
|---|---|
| 400 | A query value is invalid; field names it: topicId, cursor, limit or locale. |
| 401 | The key is missing, unknown or revoked. |
| 404 | API access is not available. |
| 429 | Too many requests; retry after the Retry-After header's seconds. |
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.
| Type | Meaning |
|---|---|
| signal.matched | data 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.corrected | An earlier match (data.matchId) was corrected at the source; re-read it. |
| signal.retracted | An earlier match (data.matchId) was retracted at the source; treat what you stored from it as withdrawn. |
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.
Verify the raw body before parsing it, compare in constant time, and reject a t more than 5 minutes away:
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:
| Tool | What it does |
|---|---|
| list_topics | locale, as above. The same result as GET /api/v2/topics. |
| list_matches | topicId, 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.