2026-10-14: a site with a path matches the publishers under it
A change in behaviour for sites that have a path; nothing changes for a site on a whole host.
- A site narrowed to a path (
example.com/sport) used to match every publisher on its host whose address was above or below that path, the whole host's publisher included. It now matches the publishers at or under its path. When no collected publisher sits exactly at the site's path, it also matches the nearest collected publisher above it, since that publisher holds the site's own pages. - What you will see: on
GET /v1/subscriptions/{id}/sitesand a site's own answer,publishersandmatchcan change for sites with a path (often fromseveraltomatched). Sites you pinned to publishers are not changed. Existing sites are re-matched over the days after this date; a site you add or edit is matched by the new rule at once. - Classification: a customer site with a path and a publisher of its own no longer makes the
host's wider publisher a customer. Detections at that wider publisher found or re-scored after
the change are classified by your other sites (
potentially_unlicensedfrom band medium up when no customer site matches it). Add the whole host as a customer site if the whole outlet is your customer. Detections already delivered are not changed.
2026-10-12: usage reports refuse a read that is too large
A change in behaviour for very large reports; nothing else changes.
GET /v1/reports/usagenow answers400 invalid_request("choose a shorter period or a coarser grouping") where a report would read too much at once: distinct publishers (metrics=publishers) bydayover several months of a busy subscription in a time zone other than UTC. Such a request answered slowly or failed before. Ask for a shorter period, or group byweekormonth. Reports withoutmetrics=publishers, and reports over shorter periods, are not affected.- A report across two content types over a full year in a time zone far from UTC answers
400("narrow the period or the subscriptions") where it failed with500before.
2026-10-09: how a text detection was matched
Additive: nothing changes or goes. Flat files (CSV, TSV) do not change.
- Text detections carry
evidence, afterarticle:kind,status(stored,missingorgone),matched_at,expires_at(45 days after the match),article_text(wholeormatched) and the addressesrecordandpack. OnGET /v1/detections,GET /v1/detections/{id}, the change stream, webhooks, and JSON Lines and JSON deliveries. Image detections carry none yet. It is worked out when answered, never stored;fields=evidenceselects it. See How it was matched. GET /v1/detections/{id}/evidenceandGET /v1/detections/{id}/evidence/pack: the record of how a text detection was matched, as JSON or as a ZIP, while EzyInsights keeps it (45 days). New problem types:evidence_gone(410),evidence_missing(404),evidence_not_available(404) andevidence_unavailable(503).- Destinations take
format_options.evidence_text: a JSON Lines side file of how each text detection was matched beside each delivery's parts, listed in the manifest'sevidence_fileswithevidence_goneandevidence_unreadable. See Matched sentences.
2026-10-09: groups, pinned publishers and labels on sites
Additive: nothing changes or goes.
- A site has
group(the agency's own group, ornull),pinnedandpublisher_ids(the EzyInsights publishers a site is pinned to instead of matched by its address; empty when it is not pinned), andlabels(up to 5 columns kept from the agency's list). GET /v1/subscriptions/{id}/sitestakesgroup, matched without regard to case.PATCH …/sitestakesgroup;PUT …/sites/{site}takesgroup,labels,publisher_ids, andpinned: falseto match a pinned site by its address again.- An import's rows take
group,publisher_idsandlabels; withtext/csv, the columnsgroup,publisher_idsandlabel:<key>. A query is cut off, and a path's last segment that names a page (index.html,contact) is dropped, keeping the rest of the path. The preview addsgroups,pinned_rows,address_rows,shared_publishers,name_mismatches,paths_droppedandunknown_ids, and on areplaceunpinned_rows,labels_cleared_rowsandunpin_too_broad; and the skip reasonsgroup_too_long,bad_publisher_idsandbad_labels.
2026-10-08: a managed image feed, and a test prefix for managed feeds
Additive: nothing changes or goes.
- A second layout in Managed legacy feeds:
imagewire-legacy-hourly, one JSON file an hour of your photo matches, set up by EzyInsights staff. - A destination has
test_prefix, read-only with a key: for a managed legacy feed, staff may set a prefix under which its connection test writes the feed's first real hourly file instead of in the feed itself. It isnullon every other destination.
2026-10-07: delivery files documented
Documentation only: nothing in the API changes.
- A new section, Deliveries: what a destination delivers, its schedules, the
files' names and parts, the manifest written last, the formats and their options, the columns of
CSV and TSV in their frozen
v1order, filters, the first delivery, retries and failing, the delivery log, credentials, the test file, and how to read deliveries safely. - A new section, Managed legacy feeds: the hourly JSON layout
newswire-legacy-hourly, set up by EzyInsights staff for agencies that receive an existing feed's layout. - A new section, Webhooks: endpoints, the rule, batches of at most 100 with one
message in flight, the body, retries,
failinganddisabled, pause, the message log, replay, the test event and secret rotation; and Webhook signatures: the headers, the secret and the signed content, with verification code in Node.js, Python and Ruby. - Corrected in the reference: a destination stays
activewhile a delivery retries and becomesfailingwhen one fails for good (disabledis not used for destinations);columnsare dot paths for JSON Lines and JSON;schema_versionislegacyfor a managed legacy feed; federation is offered for Amazon S3 and Google Cloud Storage; CSV'sheaderdefaults totrueandbomtofalse; every delivery's rows count againstlimits.daily_file_rows.
2026-10-01: destinations and webhooks by code
Additive: nothing changes or goes.
- Two new scopes, chosen when a key is made in the app:
destinations:manageandwebhooks:manage. As withsites:manage, they can be removed from a key later but never added. GET,POST /v1/destinations;GET,PATCH,DELETE /v1/destinations/{id};GET …/setup,POST …/credential,…/test,…/pause,…/resume,…/run-now, andGET …/deliveries: everything the app's Destinations page does. See Destinations and webhooks by code.GET,POST /v1/webhooks;GET,PATCH,DELETE /v1/webhooks/{id};POST …/rotate-secret,…/pause,…/resume,…/test,GET …/messagesandPOST …/messages/{message_id}/replay.- Destinations and webhook endpoints carry an
ETag(theirversion) and acceptIf-Match; a stale one is412. The creates,rotate-secretandcredentialacceptIdempotency-Key, and answerIdempotent-Replayed: truewhen they repeat a request; a repeat while the first still runs is409, and an API key may use 1,000 keys in 24 hours (429past that). New problem type:idempotency_key_reused(422).
2026-09-29: the wire story's headline
Additive: nothing changes or goes, so a client that ignores fields it does not know needs no change.
- Text detections carry the wire story's own headline as
source.headline, aftersentences: a string of at most 1,000 characters, ornulluntil our Newswire export carries it. Detections recorded before this change do not have the field until they are next scored. It is not a versioned field: a headline that appears or changes does not by itself make a new version and is not carried on the change stream;GET /v1/detectionsandGET /v1/detections/{id}give the current one. GET /v1/sourcesandGET /v1/sources/{content_type}/{internal_id}give a wire story'sheadline, afterpublished_at, from its newest detection:nulluntil a detection carries it. Photos have noheadline.
2026-09-29: 503 while the data store restarts
- A request that reaches our data store while it restarts (a deploy) is retried once on our side;
if the restart outlasts that, the answer is
503 unavailablewithRetry-After: 2rather than500 internal. Retry it after that wait, as for any503.
2026-09-25: one subscription per key, no accounts
A key belongs to one subscription and reads only its data; nothing in the API names an account. No customer held a key when this changed.
GET /v1/meanswers onesubscriptionobject (its name, content types, time zone,data_starts,customer_lists,classification_since) instead ofsubscriptions[], and no longer hasaccount. The limits are the subscription's;limits.throttledisnull,"key"or"subscription".subscription_idis optional and not repeatable on every endpoint that takes it: the key's own id is accepted, any other is400with the same text as before ("subscription 1234 is not available to this key"). The cap of 4 subscriptions per request is gone.GET /v1/reports/usage:group_by=subscriptionis withdrawn (400"subscription is not a grouping: a key has one"), and groups no longer carrysubscription_id.GET /v1/sources/{content_type}/{internal_id}: answered for the key's subscription; the "lowest subscription id" rule is gone.GET /v1/subscriptions/{id}/sites…:{id}must be the key's subscription; any other is404.- A subscription has many named keys, up to 25 usable at once. The content types a key reads are
those our exports carry for its subscription. Errors say "subscription" where they said
"account":
403"the API is suspended for this subscription", and the daily allowance's429.
2026-09-25: Sites
Sites (phase 2): customer and tracking lists per subscription; customer and classification
now filled on detections re-scored after a list exists; the filters customer= and
classification= on /v1/detections follow in a later release.
GET /v1/subscriptions/{id}/sitesandGET …/sites/{site}: a subscription's sites, with theircustomerandpriority, the publishers each matches, tracking and collection health.POST …/sites/import(JSON ortext/csv, with a dry run first),PUT …/sites/{site},PATCH …/sitesandDELETE …/sites/{site}, with the new scopesites:manage, chosen when a key is created. Every answer carries the list'sETag; writes acceptIf-Match./v1/me:customer_listsandclassification_sinceper subscription are now filled.- New problem types:
limit_reached(409),state_conflict(409),precondition_failed(412).
Expect a burst of updates when a list first exists. From the time a subscription first has a
Sites list, every detection of it that is re-scored changes from customer: null to a value and
comes through the change stream as an updated event: for text, the detections of the last 8
days, and for images of the last 30 days, over a day or two. Older detections keep null, and a
later change to the list does not re-send anything; it applies to detections found or re-scored
after it.
2026-09-25: sources and usage reports
New endpoints (additive; v1 is unchanged):
GET /v1/sources: your items that were used, with their totals over every use (detections, publishers, first and last use, best score, uses per band), selected by when they were published on your wire (published_from,published_to) or by your own item id. A first-use period (used_from,used_to), briefly offered the same day, is withdrawn: an item has one publish time, and every use found for it counts, whenever it was found.GET /v1/sources/{content_type}/{internal_id}: one used item, andGET /v1/sources/{content_type}/{internal_id}/detections: every use of it, sorted newest first, by score or grouped by publisher. Its rows count against the daily row allowance.GET /v1/reports/usage(scopereports:read): counts of detections, distinct publishers and items used for the first time, by hour, day, week or month in your time zone and by publisher, band, content type or subscription. Grouping bycountryandcustomercomes later.
v1, 2026-09-24
The first version of the EzyInsights Detections API.
Endpoints
GET /v1/detections/changes: the change stream, every new and changed detection in the order it arrived, from acursoror fromsince(at most 31 days ago).GET /v1/detections: the current state of the detections first detected in a period of at most 31 days, with filters and a query cursor.GET /v1/detections/{id}: one detection, latest version.GET /v1/me: the key, its account and subscriptions, where data starts, export gaps and limits.GET /v1/schema/detection: the v1 detection, machine-readable (alsoHEAD).POST /oauth/token: access tokens with OAuth 2.0 client credentials.GET /v1/health: whether the data is current (alsoHEAD).
The detection schema v1, for text (wire stories) and images (photos): identity and version,
source (the agency's item), strength (score and band), article (the publisher article and
publisher), and customer and classification, which are null in this version. Every field is
listed in the reference and at GET /v1/schema/detection.
Limits: 120 requests a minute per key, and a daily row allowance per account.
Deprecation policy (proposed)
Adding endpoints, parameters or fields is not a breaking change: it is announced here and made in
place, so clients should ignore fields they do not know. Renaming or removing anything, or changing
what it means, is a breaking change: it will come as a new version (a new detection
schema_version, or a new URL version), announced here with 12 months' notice, during which
answers from the old version carry Deprecation and Sunset headers. This policy is still a
proposal and will be confirmed here.