Overview
A detection is one of your items, a wire story or a photo, found in one publisher article, for your
key's subscription. It says which item (source), which article and publisher (article), how
strong the match is (strength), and when we first saw it (first_detected_at). A detection has a
stable id and a version that goes up whenever something you can see in it changes, such as a
new score or an earlier first detection. You read detections in two ways: everything first
detected in a period (GET /v1/detections), or everything new and changed since your last call
(GET /v1/detections/changes, the change stream). Data starts on the day each of the
subscription's streams begins, which GET /v1/me gives as data_starts; nothing earlier is available.
All times are ISO 8601 in UTC with Z. A field a content type does not have is absent, not null
(an image has no source.language); an unknown value is null. Every answer carries an
X-Request-Id; quote it when you write to support.
Quickstart
Get a key. Keys are created in the EzyInsights app under Settings › API › Keys, by EzyInsights staff or by an administrator of your subscription. A key looks like
ezy_live_k7f3m2x5a4bc_…and is shown once: keep it in your secret store, never in code.Check it.
GET /v1/mesays who the key is, which subscription it reads, where each stream's data starts and what your limits are:curl -s https://api.ezyinsights.com/v1/me \ -H "Authorization: Bearer $EZY_API_KEY"Start the change stream from a time in the last 31 days with
since:curl -s "https://api.ezyinsights.com/v1/detections/changes?since=2026-09-23T00:00:00Z&limit=1000" \ -H "Authorization: Bearer $EZY_API_KEY"Store
next_cursorfrom every answer, together with the rows it brought, and pass it ascursornext time instead ofsince. Whilehas_moreis true, call again at once.Poll hourly with the stored cursor. When nothing is new you get an empty page and the same cursor back.
Upsert by
id, keeping the higherversion. Delivery is at least once, so the same version can arrive twice, and an older version must never overwrite a newer one.
A complete loop in Python, standard library only (run it hourly, for example from cron):
import json, os, sqlite3, time, urllib.error, urllib.parse, urllib.request
from datetime import datetime, timedelta, timezone
API = "https://api.ezyinsights.com"
KEY = os.environ["EZY_API_KEY"] # ezy_live_...; never in the code
db = sqlite3.connect("detections.db")
db.execute("CREATE TABLE IF NOT EXISTS detections (id TEXT PRIMARY KEY, version INTEGER, body TEXT)")
db.execute("CREATE TABLE IF NOT EXISTS state (name TEXT PRIMARY KEY, value TEXT)")
def get(path, params):
url = API + path + "?" + urllib.parse.urlencode(params)
request = urllib.request.Request(url, headers={"Authorization": "Bearer " + KEY})
for attempt in range(6):
try:
with urllib.request.urlopen(request, timeout=60) as answer:
return json.load(answer)
except urllib.error.HTTPError as error:
wait = int(error.headers.get("Retry-After") or 2 ** attempt)
if error.code not in (429, 500, 503) or wait > 300:
raise # 429 daily_allowance waits until 00:00 UTC: stop and run again later
time.sleep(wait)
raise RuntimeError("the API kept failing; try again later")
row = db.execute("SELECT value FROM state WHERE name = 'cursor'").fetchone()
if row:
params = {"cursor": row[0]}
else: # the first run: start a day ago (at most 31 days)
since = datetime.now(timezone.utc) - timedelta(days=1)
params = {"since": since.strftime("%Y-%m-%dT%H:%M:%SZ")}
while True:
page = get("/v1/detections/changes", {**params, "limit": 1000})
for d in page["data"]:
db.execute(
"INSERT INTO detections VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET "
"version = excluded.version, body = excluded.body WHERE excluded.version > detections.version",
(d["id"], d["version"], json.dumps(d)),
)
db.execute("INSERT OR REPLACE INTO state VALUES ('cursor', ?)", (page["next_cursor"],))
db.commit() # the rows and the cursor together
if not page["has_more"]:
break
params = {"cursor": page["next_cursor"]}
For history older than 31 days, make a full copy first (next section), then run this loop.
A full copy, gap-free
The change stream starts at most 31 days back. To hold everything since your data starts:
- Read the first page of
GET /v1/detectionsfor the most recent month and keep itsas_of. - Walk
GET /v1/detectionsmonth by month back todata_starts(fromGET /v1/me), followingnext_cursoruntilhas_moreis false in each month, and upsert every row byid, keeping the higherversion. - Start the change stream with
sinceset to that firstas_of, and keep following it as in the quickstart.
Anything that changed during the walk, including a first detection moving into a month you had
already read, or a late file, reaches the stream after that as_of, so the stream carries it. Use
the server's as_of, not your own clock, and start the stream within 31 days of it.
Authentication and keys
Send the key, or an access token, in the Authorization header of every request:
Authorization: Bearer ezy_live_k7f3m2x5a4bc_…
- The format.
ezy_live_, then the key id (12 characters), an underscore and the secret (52 characters), all lower-case lettersa–zand digits2–7. The key id names the key in/v1/meand the app; the secret is shown once, when the key is made, and we keep only a hash of it. - Never in a query string. Keys and tokens are read from the
Authorizationheader only; a key in the URL is ignored and the request is refused with401. - What a key reads. A key is made for one subscription and reads only its data. A subscription
can hold many keys (up to 25 usable at once), each named for the project or service it serves. No
answer names or counts any other subscription; asking for one is
400with the same words whether it exists or not, and a detection id outside the key's subscription is404. - Optional limits on a key. An expiry date, and a list of addresses (IPv4 or IPv6, single or
CIDR) it may be used from; from any other address it is refused with
403. - Rolling a key. In the app, Roll key makes a new key with the same name and scope and keeps the old one working for the overlap you choose (1 hour, 24 hours or 7 days), after which it expires by itself. Deploy the new key within the overlap. Cursors survive a roll.
- Revoking a key. Revoke key stops the key, and every token made from it, within a minute. It cannot be undone.
A revoked, expired or unknown key is 401 unauthorized; a key of a subscription whose API is
suspended is 403 forbidden.
Tokens
If your client prefers OAuth 2.0, exchange a key for an access token with the client credentials
grant, and send the token as Authorization: Bearer <token> like a key:
curl -s https://api.ezyinsights.com/oauth/token \
-d grant_type=client_credentials \
-d client_id=k7f3m2x5a4bc \
-d "client_secret=$EZY_API_SECRET"
{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600,
"scope": "detections:read reports:read exports:create" }
- Two ways to send the credentials:
client_id(the key id) andclient_secret(the secret) in the form body, or as HTTP Basic,Authorization: Basic base64(<key id>:<secret>); not both. As a convenience the whole key (ezy_live_…) is also accepted asclient_secretwhen its id matchesclient_id. - The body is
application/x-www-form-urlencoded, at most 4 KiB, with no parameter given twice;grant_typemust beclient_credentials. - Lifetime: one hour (
expires_in: 3600). When a token expires, requests answer401("the access token has expired"); request a new one. Tokens are not stored and cannot be revoked one by one: revoking the key stops its tokens within a minute. - Scopes. Every key has
detections:read,reports:readandexports:create. Ask for fewer withscope(space-separated, a subset of the key's); leave it out for all of them. On every request the token's scopes are intersected with the key's current ones. - Limits: at most 10 token requests a minute per client id and per address. A token lasts an hour, so one request an hour is enough.
The change stream and its guarantees
GET /v1/detections/changes gives every new and changed detection in the order it reached us,
each with event, created or updated.
- At least once. A detection version may be delivered more than once (after a retried file).
- Upsert by
id;versionnever decreases for an id across the stream. last_scored_atin the stream is as of the version delivered. A re-scoring that changes nothing else does not create a new version, soGET /v1/detections/{id}may show a laterlast_scored_at.- Order is ingest order, not detection time. Recovery files and re-scorings arrive when they arrive.
first_detected_atcan move earlier when an older evaluation of a match is processed after a newer one; that arrives as anupdatedevent with a higherversion.
How to read it:
- Start with
since, a time at most 31 days ago and not in the future: the stream starts at the first change delivered at or after it. Afterwards, always pass thecursorfrom your last answer. One of the two is required, never both. - The cursor is a position in the stream. It never expires, survives a key roll and is valid with any filter. Store it with the rows it brought.
- Pages. A page stops at
limitrows (at most 1,000) or after 50 chunks of the stream (a chunk is one export file's changes for one subscription), whichever comes first. So a page can hold fewer rows thanlimit, even none, withhas_more: true: call again withnext_cursoruntilhas_moreis false, then poll later with the last cursor. - An empty stream. When none of your streams holds anything at or after
since, the answer is an empty page withhas_more: falseand a cursor at the end of the newest stream; poll from it. When you are caught up, the cursor you get back is the one you sent. - Streams per request. Each content type of your subscription is one stream, and one request
reads at most 20, so every request reads all of yours (two at most today); narrow it with
content_typeif you want one. - Filters (next sections but one) are applied to each row. Changing them between calls is allowed, but rows an earlier filter skipped are not delivered again.
Detections in a period
GET /v1/detections?from=…&to=… gives the current state of every detection first detected in the
period: for reports, checks and looking back.
fromandtoare required. Each is a date (2026-09-23) or an ISO 8601 time withZor an offset (2026-09-24T10:00:00Z).fromis inclusive andtoexclusive, except that a date-onlytoincludes its whole day:from=2026-09-23&to=2026-09-23is one day, andto=2026-09-30includes the 30th. Atoin the future is read as now.- Time zones. A date is read in the request's time zone:
time_zoneif you give one (an IANA name such asEurope/Berlin), else the subscription's own time zone. Days follow the zone's clock changes. Every answer echoes the resolvedfromandto(as UTC times) andtime_zone. - At most 31 days. 31 calendar days when
fromandtoare both dates, so a whole month is always one request; otherwise 31 × 24 hours, plus one hour for a clock change, between the two times. Walk longer periods month by month. - Not before data starts.
frommay not be earlier than the day records begin: the earliestdata_starts(GET /v1/me) of the requested streams, that day's start in the request's time zone. The400namesdata_starts. - Sorts.
sort=-first_detected_at(the default, newest first) orsort=first_detected_at(oldest first); ties are broken byid. - Paging.
limitis up to 1,000 when the request covers one stream (one content type) and up to 200 when it covers more. Follownext_cursoruntil it is null.has_morecan be true with an empty next page. - The query cursor refuses a changed request. It carries a hash of the period, the time zone,
the sort, the content types, the filters and
fields, so a walk cannot silently change its question halfway: a cursor sent with anything changed is400("the period or filters changed; start again"). Onlylimitmay change between pages. - Wide requests. A request whose period reaches more than 64 shards of our storage is
400("narrow the period or the subscriptions"). - No
event. Detections here are states, not changes;eventbelongs to the change stream. The same holds forGET /v1/detections/{id}.
What you must know:
- The answer is the current state: a detection re-scored tomorrow shows tomorrow's values.
- A period that ended less than two days ago is still filling, and a walk through it is not a consistent snapshot: matches keep arriving for about a day and a half, and a detection's first detection can move earlier when an older evaluation arrives late, which can move it to a page already read. Newest-first (the default) keeps new arrivals ahead of the cursor. For a complete, updating copy, use the change stream.
- Detections exist from each subscription's
data_starts(GET /v1/me).
Filters and fields
The detection endpoints GET /v1/detections and GET /v1/detections/changes take the same
filters, all combinable. A repeatable filter also takes a comma-separated list
(publisher_id=42,43 is publisher_id=42&publisher_id=43).
| Filter | Rules |
|---|---|
subscription_id |
Optional, one value: the key's own subscription. Any other is 400 ("subscription 1234 is not available to this key") |
content_type |
text or image. Unset: every type the key reads |
publisher_id |
Repeatable, up to 50: only these publishers. A detection without a publisher never matches |
exclude_publisher_id |
Repeatable, up to 50: every publisher but these |
domain |
Repeatable, up to 20: only articles on these domains. A domain, or an http(s) URL without a path; compared in lower case and punycode (münchen.example is xn--mnchen-3ya.example) |
exclude_domain |
Repeatable, up to 20: every domain but these |
min_band |
This band or stronger (below) |
band |
Repeatable: exactly these bands (band=medium&band=high) |
min_score |
0 to 100: strength.score, rounded to a whole number, at least this |
print |
true or false. Image detections are never print |
source_id |
Your own id for the item (source.id), exactly, at most 200 characters |
article_id |
One publisher article (article.id) |
min_band for each content type. Text bands run off < low < medium < high < max
(usage thresholds 25, 50, 75 and 95%); image bands run low < medium < high (score thresholds
30 and 60). The same word is the same step for both types, so min_band=medium keeps text
medium, high and max and image medium and high; min_band=off keeps everything; and
min_band=max keeps only text max and excludes every image. With band, off and max match
no image.
fields returns only the fields you name, so a loader that needs eight columns does not
download forty: fields=first_detected_at,strength,article.url,article.publisher. A path is a
field of the schema or an object holding some (source, strength, article,
article.publisher), which comes back whole. id and version always come back, the detection's
order is kept, and a field the content type does not have stays absent. fields also works on
GET /v1/detections/{id}. Every field is listed under Schemas, and
machine-readably at GET /v1/schema/detection.
Strict parameters. On the detection endpoints, a parameter the endpoint does not know is 400,
and so is an empty value or a single-valued parameter given twice; the detail names it. schema_version=v1 (the default and
only version) is accepted by every detection endpoint and by /v1/schema/detection.
How it was matched
Every text detection carries evidence, after article: how it was matched, in brief.
Image detections carry no evidence yet; it comes with image evidence later.
"evidence": {
"kind": "text",
"status": "stored",
"matched_at": "2026-10-23T07:02:11Z",
"expires_at": "2026-12-07T07:02:11Z",
"article_text": "whole",
"record": "https://api.ezyinsights.com/v1/detections/t.9001.5000001.7000001/evidence",
"pack": "https://api.ezyinsights.com/v1/detections/t.9001.5000001.7000001/evidence/pack"
}
status:storedwhile the record is kept;missingfor a print use (no page was collected, so no record will ever exist);gonefromexpires_aton.expires_at:matched_atplus 45 days. EzyInsights keeps the sentences behind a text match for 45 days. Fromexpires_aton,GET …/evidenceanswers410 Gone, for good. What you download is yours to keep: fetch the record, or turn on matched sentences for a destination, while it is kept.article_text: what the record carries of the publisher's article.wholewhen the publisher is one of your customers, or the usage ismediumor above; otherwisematched, the passages at similarity 0.65 and over in full and the rest counted, not shown.- The field is worked out when the detection is answered, never stored: on
GET /v1/detectionsandGET /v1/detections/{id}it is as of your request. On the change stream, webhooks and delivered files it is as of when the row was sent; readexpires_atto know until when the record answers.fields=evidence, or a path inside it, selects it like any other object.
GET /v1/detections/{id}/evidence answers the record while it is kept: the envelope, the use's
own facts (use), and how it was matched: matched (how often the pair was matched, and whether
the evaluation shown is the one the detection records: exact), recorded (the detection's own
usage), usage (counted from the pairs at similarity 0.65, 0.80 and 0.95), story (your story's
version the match saw, sentence by sentence) and article (their article, a sentence an entry, each
with your nearest sentence and how alike the two are, 0 to 1). A use whose record is not found yet,
while its match is under two hours old, answers 200 with status: pending. A use taken down on a
legal request answers 200 with status: suppressed and no texts.
GET /v1/detections/{id}/evidence/pack is the same as a ZIP to keep: a README.txt, the
comparison as a page you can open or print, their article and your story as numbered text, the
record as JSON and the detection. It is made as you download it and stored nowhere.
Both need detections:read, take an id in the key's scope (anything else is 404 not_found, as
for the detection) and count as one row each of the daily row allowance. Their refusals:
| Status | type |
When |
|---|---|---|
410 |
evidence_gone |
From expires_at on; the problem carries expires_at |
404 |
evidence_missing |
A print use, or no record found more than two hours after the match |
404 |
evidence_not_available |
An image detection |
503 |
evidence_unavailable |
The record could not be read just now; retry after Retry-After |
Sources
A source is one of your items (a wire story or a photo) that was used at least once. Items
never used are not known to us and are not listed. Each source comes with its totals over every
use found for it, whenever it was found: detections, distinct publishers (a publisher id, or a
domain for uses without one), its first and last use, its best score and its uses per band.
GET /v1/sources?content_type=image&… lists sources. content_type is required, and so is
one of these:
published_fromandpublished_to: the photos and articles published on your wire in the period, ranked bysort:-detections(the default),-publishers,-first_detected_ator-published_at. The period is about when an item was published, not when it was used: every use found for it counts, whenever it was found. We track an item for up to about 30 days after it is published, so the totals of items published in the last month can still grow. The two count sorts page on counts that can grow: an item that gains uses between two pages can move above the cursor and be skipped (never repeated); the other sorts are stable.published_frommay be earlier thandata_starts: an item published before we began recording can still be used after.source_id: the item with your own id (a URN, a UUID…), in one page with no cursor.
A period may be at most 31 days, read like /v1/detections' (dates in the request's time zone, a
date-only end includes its day). limit is up to 500; the cursor refuses a changed period, sort
or time zone, like the detections' query cursor. A request reaching more than 64 shards of our
storage is 400.
GET /v1/sources/{content_type}/{internal_id} gives one source, and
GET /v1/sources/{content_type}/{internal_id}/detections every use of it, as detections (without
event, with the shared filters except source_id, and fields), for your key's subscription.
An item that is unknown, never used or outside your key's scope is 404. The detections sort newest first (the default), by score (sort=-score), or grouped by
publisher (sort=publisher: by publisher id, uses without a publisher first, newest first within
one; a grouping, not an alphabetical order). limit is up to 1,000. The rows it returns count
against the daily row allowance; the other two source endpoints do not.
Usage reports
GET /v1/reports/usage?from=…&to=…&group_by=day,publisher counts your uses, with the
reports:read scope. It answers groups: one per time bucket and per value of the other groups,
each with detections, and with publishers (distinct publishers) and new_sources (items used
for the first time) when you ask for them with metrics.
group_by: up to two ofhour,day,week,month(one of these at most),publisher,bandandcontent_type. Without a time grain, the whole period is one group. There is nosubscriptiongroup: a key reads one subscription.countryandcustomerare coming; until then they are400("not available yet").- Buckets in your time zone. Days, ISO weeks (Monday start) and months are counted in
time_zone, else the subscription's own zone; hours are whole UTC hours, labelled with their local start. We count by the hour, so in a zone whose offset is not a whole hour (India +5:30, Nepal +5:45, Adelaide +9:30) each boundary is moved to the nearest hour and the answer says"approximate_days": true. new_sourceshas two meanings. Withoutpublisheringroup_by, it counts the items used for the first time in the bucket, at any publisher. Withpublisher, it counts the items used for the first time at that publisher: an item first used by two publishers counts once for each, so the publisher groups add up to more thantotals.new_sources, which always counts each item once. For the same reasonnew_sourceswith apublisher_idfilter is400unless you group bypublisher.publishersis exact within one content type and one UTC year. A report that spans several of them (two content types, or a year boundary) adds their counts, so a publisher can be counted more than once, and the answer says"publishers_summed": true. Group bycontent_typefor exact counts.- Filters:
subscription_id,content_type,min_band,bandandpublisher_id, as on the detection endpoints. - Caps. At most 7 days grouped by
publisherandhour; at most 92 days bypublisheranddayorweek; otherwise at most 366 days. A report of more than 10,000 groups in one subscription, content type and year is400("narrow the period or the grouping"). A report that would read too much at once is also400("choose a shorter period or a coarser grouping"): this can happen withmetrics=publishersbydayover several months of a busy subscription in a time zone other than UTC, where grouping byweekormonthanswers.frommay not be earlier than the day records begin. - Paging. Groups are ordered by time bucket, then
detections(most first), then the other keys.limitis up to 10,000 groups a page (default 1,000). The cursor is an offset with a hash of the request: it refuses a changed request, but if data arrives between two pages a group can move and appear twice or not at all. Read a report in one sitting, or ask for everything in one page.
Limits and allowances
- 120 requests a minute per key. Answers to an accepted key or token carry
RateLimit-Limit: 120andRateLimit-Policy: 120;w=60. Over it,429with typerate_limitedandRetry-After: 60. The limit is counted per Cloudflare location, best effort, so a client spread over several locations can exceed it; no remaining count is given. - Unknown credentials are rate-limited. Requests with key ids we have not recently seen are
limited per address (about 10 a minute); over that,
429 rate_limited. - Tokens: 10 requests a minute per client id and per address.
- The daily row allowance. Each subscription may read a number of detection rows per UTC day: the
rows returned by
/v1/detections,/v1/detections/changesand/v1/detections/{id}count./v1/meshows it aslimits.daily_rows. By default it is the larger of 1,000,000 and three times the rows the subscription produced in the last 31 days, so a runaway client can re-read about a month three times a day before it stops. Ask us to raise it for a large backfill. - Keys before the subscription. When a subscription goes over, its keys are throttled, those that read the most first, until the rest fit, so a runaway test script does not stop your production loader. The whole subscription is throttled only when a single key (with the keys it was rolled from) is over on its own; rolling a key does not reset its count. Another subscription's use never throttles yours.
- Throttled: the detection endpoints answer
429with typedaily_allowance, the reset time (the next 00:00 UTC) in thedetail, andRetry-Afterwith the seconds until then. The cursor you hold stays valid and nothing is lost./v1/me,/v1/schema/detectionand/oauth/tokenkeep working, and/v1/meshowslimits.throttled(keyorsubscription) withthrottled_until. - "About". The allowance is counted from our request metering every five minutes, so it takes effect about 8 minutes after it is passed. At the fastest possible rate (25 keys × 120 requests × 1,000 rows a minute) a subscription can read up to about 24 million rows past it before it is throttled.
Errors
Every error except the token endpoint's is a problem document (RFC 9457), sent as
application/problem+json:
{ "type": "https://api.ezyinsights.com/errors/invalid_request", "title": "Invalid request",
"status": 400, "detail": "limit must be between 1 and 1000",
"request_id": "0b6f1c9e-3a52-4d8e-9f0a-6c1d2e3f4a5b" }
The detail says what was wrong in plain English; request_id is the answer's X-Request-Id.
| Status | Type | When |
|---|---|---|
| 400 | invalid_request |
A parameter is unknown, empty, repeated or out of range; a cursor this endpoint did not give; a query cursor with a changed request; a filter naming a subscription or content type the key does not read; a malformed detection id |
| 401 | unauthorized |
No credential, or a malformed, unknown, expired or revoked one. Carries WWW-Authenticate: Bearer |
| 403 | forbidden |
The credential lacks the endpoint's scope, the address is not allowed for the key, or the API is suspended for the key's subscription |
| 404 | not_found |
No endpoint at this path (a trailing slash never matches), or no detection with this id for this key; no used item at /v1/sources/{content_type}/{internal_id} (unknown, never used or not this key's, all alike); for Sites, a subscription or site that is not this key's |
| 405 | method_not_allowed |
The path exists but not with this method; Allow lists the methods it answers. Among the API's endpoints, HEAD is answered on /v1/health and /v1/schema/detection only |
| 409 | limit_reached |
A Sites list would hold more than 10,000 sites; the detail says by how many |
| 409 | state_conflict |
A Sites change conflicts with the list: rows overlap listed sites without confirm_overlaps (a PUT of a new overlapping site too: add it with an import), or the host and path are another site's |
| 412 | precondition_failed |
The Sites list changed since the If-Match version; the ETag is its version now |
| 413 | content_too_large |
A token request body over 4 KiB; a Sites body over 5 MB or 20,000 rows |
| 429 | rate_limited |
Over a rate limit; wait Retry-After seconds |
| 429 | daily_allowance |
The key or its subscription has used its daily row allowance; Retry-After is the time to 00:00 UTC |
| 500 | internal |
Our fault; retry with backoff |
| 503 | unavailable |
Credentials cannot be verified right now, or our data store is restarting (a deploy; Retry-After: 2); retry with backoff |
The token endpoint answers errors as RFC 6749 does, { "error", "error_description" }:
400 invalid_request (not a form, a parameter twice, credentials both in the body and as Basic,
malformed Basic credentials), 400 unsupported_grant_type, 400 invalid_scope (a scope the key
does not have) and 401 invalid_client (wrong credentials, or a key that may not be used; with
WWW-Authenticate: Basic realm="ezy-data" when Basic was used). A body over 4 KiB (413), the
rate limit (429) and service faults (500, 503) are problem documents as above.
Retry 429, 500 and 503 after a wait, doubling it each time; never retry 400, 401, 403
or 404 unchanged.
Where data starts and gaps
data_starts.GET /v1/megives, per subscription and content type, the time the stream's records begin: the later of the start (00:00 UTC) of its first day of data and the time the export itself began.nullmeans the stream has no data yet.GET /v1/detectionsrefuses afrombefore that day.- History counts. Once a subscription's two-year history is loaded,
data_starts.textmoves back to its first history day andGET /v1/megainshistory_until: the time before which its text counts come from the history snapshot, per subscription, once that subscription's load is done. The detections themselves are not served before the line:GET /v1/methen also givesrows_start, whereGET /v1/detectionsbegins (it refuses afrombefore that day), whileGET /v1/reports/usagecounts back todata_starts. Those counts hold one evaluation per (story, article): the latest as of the snapshot. Rows without a usage band are left out. About 0.6% of matches are missing from the snapshot (articles removed before it was taken). A use scored in the eight days beforehistory_untiland scored again after it is counted once, in the hour of its later score, so those eight days are a little low. First uses (new_sources) are counted per UTC year, as they always are, and separately on each side ofhistory_until: a story used just before it and again after it can be a first use on both sides. data_gaps. Detections arrive in export files, one per 10-minute window. A window whose file never arrived, or could not be read, is invisible in the stream, soGET /v1/melists, per content type, the windows of the last 90 days that aremissing(not arrived a day after it was due; still looked for once a day, and filled if it comes),abandoned(missing for 30 days and no longer looked for) orfailed(arrived but could not be read, until we reset it), newest first, at most 200 each. Use it to tell "no matches" from "no data" when you reconcile.as_of. Every detection answer carriesas_of: the end of the newest finished export window, the earliest over the content types read. Everything up to it has been read; newer windows may still be arriving. It isnullwhile an export has no finished window.GET /v1/healthneeds no key. It answers200withstatus: ok, and503withstatus: degradedwhile one of our alerts that needs someone is open (alerts.page_worthyabove 0), with each export'snewest_done. The one you will meet is ingest stalled: it opens when an export's newest finished window ended more than 45 minutes ago, checked every five minutes, so health turns503about 45 to 50 minutes after the last finished window. During a deliberate pause of ingest for maintenance (alerts.pausedis 1) the windows' age is not judged, so a pause alone keeps health at200;as_ofshows how far the data reaches.
Sites
A site is a place on the web your agency cares about: a host (example.de, or a host under
it such as sport.example.de), optionally narrowed by a path (msn.com with /de-de/nachrichten),
with two attributes of yours, customer (you license it) and priority (high, normal or
low). Each subscription has one list of sites, up to 10,000. We match every site to EzyInsights
publishers, track it (a site we do not collect yet is requested, and we act on the request), and
measure how well it is collected. Read the list with GET /v1/subscriptions/{id}/sites (scope
detections:read) and one site with …/sites/{site}, by id or by its URL-encoded host[/path];
changing the list needs a key created with the sites:manage scope.
An import, from JSON rows or a CSV file, in three steps:
POST …/sites/importwith"dry_run": trueanswers the preview and the list'sversion.- Check the preview: the sites to add, change or remove, the rows skipped and why, the overlaps.
- Send the same rows without
dry_run, withIf-Match: "<version>";412means the list changed meanwhile: start again.
Every answer under …/sites carries the list's ETag, and PUT, PATCH and DELETE accept it
as If-Match too; without it a write is still made against the version it reads. A URL in a row is
reduced to its registrable domain unless you set keep_host; rows overlapping a listed site are
kept only with confirm_overlaps.
A change applies to matches found or re-scored after it. A detection's customer and
classification come from the list as it stood when the detection was found or last re-scored;
changing the list does not re-send old detections. Before a subscription has a list its detections
carry customer: null (not classified), and /v1/me gives classification_since once it has one.
The filters customer= and classification= on the detection endpoints come in a later release.
Deliveries
A destination writes your detections as files to a bucket of yours, on a schedule. The rows
are the change stream's: every new and changed detection of your subscription, each with event,
in the order it reached us, so a loader that reads files gets what a client of
GET /v1/detections/changes gets. Destinations are set up in the app under Settings › API ›
Destinations, by EzyInsights staff or an administrator of your subscription, or by code
(Destinations and webhooks by code). A subscription has at
most 10.
What a destination delivers
- Everything your subscription carries: its text detections (Newswire matches: wire stories
found in articles) and its image detections (Imagewire matches: photos found in articles). When
it carries both, a destination delivers both, or only one with the filter's
content_types. Videowire matches are not delivered yet. - Where: Amazon S3 (
s3, with itsregion), a store that speaks the S3 API at a publichttpsaddress of its own (s3_compatible, with itsendpoint), or Google Cloud Storage (gcs). Azure Blob Storage is not offered yet. Files go under the destination'sprefixin itsbucket; a prefix never starts with/and always ends with one (we add it), or is empty. - Schedules: every so many minutes, from 10 minutes to 7 days (10,080 minutes) in steps of 10
(
{"kind": "interval", "minutes": 60}), once a day at a local time ({"kind": "daily", "at": "06:00", "time_zone": "Europe/Berlin"}), or once a week ({"kind": "weekly", "day": "monday", "at": "06:00", "time_zone": "Europe/Berlin"}). Due deliveries are picked up every five minutes, so one starts up to five minutes after its time. A daily or weekly time follows the zone's clock changes: a time the clocks skip runs as far after the gap as it was into it (02:30 runs at 03:30), a time they repeat runs once, the second time. One delivery always catches everything up: after a pause or a late run there is no burst of catch-up deliveries. - One delivery at a time. Each holds everything new since the previous one, up to the newest
data when it is planned. If nothing is new, or the filter keeps nothing, the delivery is
emptyand writes no file at all.
Files and their names
<prefix><YYYY>/<MM>/<DD>/ezyinsights-<S>-<from>-<to>-part-<NNNN>.<ext>
<prefix><YYYY>/<MM>/<DD>/ezyinsights-<S>-<from>-<to>.manifest.json
<YYYY>/<MM>/<DD>is the UTC date the delivery was planned, not the date of its detections.<S>is your subscription id.<from>and<to>are the delivery's place in the stream, each<seq>_<row>(a chunk of the stream and the rows of it read), as the manifest'sstream_fromandstream_togive them. The next delivery's<from>is this one's<to>.<NNNN>numbers the parts from0001. A part ends at 100,000 rows or 64 MB before compression, whichever comes first.<ext>isjsonl,csv,tsvorjson, with.gzwhen compressed.
Every file is uploaded with its Content-Type, Content-Encoding: gzip when compressed, and its
SHA-256 as object metadata (sha256: x-amz-meta-sha256 on S3, x-goog-meta-sha256 on Google
Cloud).
The manifest is written last, after every part, and only then is the delivery done. It is
uncompressed JSON:
{
"delivery_id": "dlv_…",
"destination_id": "dst_…",
"schema_version": "v1",
"format": "csv",
"compression": "gzip",
"columns": ["id", "version", "event", "content_type", "…"],
"stream_from": { "seq": 18443, "row": 12 },
"stream_to": { "seq": 18911, "row": 40 },
"planned_at": "2026-10-07T06:00:03Z",
"rows": 238114,
"parts": [
{ "key": "ezyinsights/2026/10/07/ezyinsights-9001-18443_12-18911_40-part-0001.csv.gz",
"rows": 100000, "bytes": 8123456, "sha256": "…" }
]
}
| Field | Meaning |
|---|---|
delivery_id, destination_id |
The delivery (as the delivery log names it) and its destination |
schema_version |
v1, the detection schema the rows follow |
format, compression |
As the destination had them when the delivery was planned |
one_document_per_part |
true, for the JSON array format only: each part is one complete array |
columns |
The columns in the files, in their order: flat column names for CSV and TSV, dot paths for JSON Lines and JSON |
stream_from, stream_to |
The delivery's place in the stream, as in the file names |
planned_at |
When the delivery was planned |
rows |
Detections in all parts together |
parts |
Each part's full key, rows, size in bytes as stored (after compression) and SHA-256 of those bytes |
Reading deliveries safely. Act on a manifest, never on a part alone: when a manifest appears,
read exactly the parts it lists and check each part's SHA-256. A part with no manifest belongs to a
delivery still running, or to one that failed; a failed delivery's detections come again in the
next delivery, under other names. As on the change stream, delivery is at least once: upsert by
id, keeping the higher version.
Retries write the same files. A delivery's names come from its place in the stream, so a retried delivery writes the same keys again with the same bytes, overwriting what an earlier attempt left; nothing is doubled under a new name.
Formats and compression
format |
Each part is | Content-Type |
|---|---|---|
jsonl |
JSON Lines: one detection per line, each line ending in \n |
application/x-ndjson |
json |
One JSON array of detections, [, rows separated by , and a line break, ]; it parses on its own |
application/json |
csv |
CSV (RFC 4180), UTF-8, lines ending in \r\n |
text/csv; charset=utf-8 |
tsv |
Tab-separated values, UTF-8, lines ending in \r\n |
text/tab-separated-values; charset=utf-8 |
- Compression:
gzipornone. Parquet and Avro, andzstd, are not offered yet. - CSV options (
format_options):delimiter,(the default) or;;header, a first row of column names (defaulttrue);bom, a UTF-8 byte order mark first, for spreadsheets (defaultfalse). A value is put in double quotes when it holds a"(written twice), a comma, the delimiter or a line break. - TSV options:
headerandbom, as for CSV. Nothing is quoted: a tab or a line break inside a value is written as one space, so every line is one row and every tab a column boundary. - JSON Lines and JSON take no options.
Columns
JSON Lines and JSON carry each row as the v1 detection, nested, exactly as the change stream
answers it (the Detection schema), event included. CSV and TSV carry it
flat: each field is a column, named by its path with . as _ (article.publisher.id is
article_publisher_id), always in this order, which is frozen for schema v1:
| Column | Type | Content types | Meaning |
|---|---|---|---|
id |
string | text, image | The detection's id, stable forever |
version |
integer | text, image | 1 when first seen; one more whenever a field you can see changes |
event |
string | text, image | created or updated |
content_type |
string | text, image | text or image |
match_type |
string | text, image | sentence_fingerprint for text, image_fingerprint for images |
subscription_id |
integer | text, image | Your subscription |
first_detected_at |
timestamp | text, image | When the match first reached us |
first_detected_estimated |
boolean | text, image | true when first_detected_at is estimated (a backfilled row) |
last_scored_at |
timestamp | text, image | When the match was last scored |
exported_at |
timestamp | text, image | When we wrote the row |
source_id |
string | text, image | Your own id for the item: a URN, a NewsML id, a UUID |
source_internal_id |
integer | text, image | Our id for the item |
source_published_at |
timestamp | text, image | When the item was published on your wire |
source_language |
string | text | The wire story's language |
source_syndicated |
boolean | text | Whether the wire story is syndicated |
source_sentences |
integer | text | The wire story's sentence count |
source_headline |
string | text | The wire story's own headline, as supplied |
source_image_url |
string | image | Our permanent address of your full-size photo |
source_origin_url |
string | image | Where your photo came from |
strength_score |
number | text, image | Text: the share of the wire story used, 0 to 100; image: the score, 0 to 99 |
strength_band |
string | text, image | The band: text off, low, medium, high, max; image low, medium, high |
strength_matched_sentences |
integer | text | How many of the wire story's sentences the article used, estimated |
strength_article_sentences |
integer | text | The article's sentence count |
article_id |
integer | text, image | The publisher article |
article_url |
string | text, image | The article's canonical URL |
article_domain |
string | text, image | The article's registrable domain |
article_published_at |
timestamp | text, image | When the article was published, when known |
article_headline |
string | text, image | The article's headline |
article_publisher_id |
integer | text, image | The publisher's id |
article_publisher_name |
string | text, image | The publisher's name |
article_print |
boolean | text | Whether the publisher is a print title |
article_image_url |
string | image | The publisher's copy of the photo |
customer |
boolean | text, image | Whether the publisher is on your customer list |
classification |
string | text, image | licensed, potentially_unlicensed or unknown |
- Which columns a file has: every column one of the destination's content types has. A destination that delivers text only has no image columns, and one that delivers images only has no text columns; one that delivers both has all 34, with the other type's columns empty in each row.
- Cells: empty for a null or absent value;
trueorfalse; times as ISO 8601 in UTC with whole seconds andZ(2026-10-07T06:00:03Z); numbers as plain digits. - Choosing columns (
columns): a list of names, or null for all. For CSV and TSV, flat column names from the table; the file keeps the table's order whatever order you give. For JSON Lines and JSON, dot paths (id,strength.band,article.publisher): an object path keeps the object whole, and only the paths named are written, so nameidandversionif you upsert. An unknown name is400. The manifest'scolumnssays what the files hold.
Filters
filter narrows what a destination delivers; every field is optional, and all given must hold.
| Field | Rules |
|---|---|
content_types |
text, image or both; only types your subscription carries |
min_band |
This band or stronger, as min_band on the detection endpoints (Filters and fields): max keeps only text max and no images |
domains |
Up to 50: only articles on these domains. Compared with article.domain, the registrable domain, in lower case and punycode, so give example.de, not www.example.de. An article without a domain never matches |
publisher_ids |
Up to 50: only these publishers. A detection without a publisher never matches |
A changed filter, format, compression or column list applies to deliveries planned after the change. Detections already delivered, or skipped by an earlier filter, are not delivered again.
The first delivery
On creation, start says where the destination's stream begins: now, data_start (the start of
your data, data_starts in GET /v1/me), or a time at or after it. The first delivery then holds
every detection that reached us from that time on; the change stream's 31-day limit does not
apply. A start whose first delivery would hold more than 5,000,000 rows, or more than is left of
today's file allowance (limits.daily_file_rows in GET /v1/me), is refused with 409 and the
estimate: start later, or ask us for an export.
A new destination is setting_up and delivers nothing until a connection test has passed and it is
started. Starting it queues its first delivery at once; later ones follow the schedule.
Matched sentences
With format_options.evidence_text: true, any format, each delivery whose rows include text
detections also writes a JSON Lines side file of how each was matched, beside its parts:
ezyinsights-<S>-<from>-<to>-evidence-0001.jsonl.gz (gzip whenever the destination compresses;
.jsonl with compression none), one line a
text detection, in stream order, { "id": …, "evidence": … } with the evidence as
GET /v1/detections/{id}/evidence answers it. A file is cut at 10,000 lines
or 64 MB before compression. A line whose record is no longer kept is still written, with
status: gone and no texts, so you know the row was in the delivery; a print use's has
status: missing, one taken down on a legal request status: suppressed, and one whose record is
not found yet status: pending. A record that exists but can never be used (it cannot be parsed,
is over its size cap, or names another pair) gets a line with status: unreadable and no texts.
The manifest lists the side files under evidence_files (each one's key, lines, bytes and
SHA-256), and counts the gone lines in evidence_gone and the unreadable ones in
evidence_unreadable; its
schema_version stays v1, and the parts do not change. Turn it on only for a destination that
carries text; a managed legacy feed never carries it.
A first delivery of your history has the sentences for the last 45 days only: older text
detections get a gone line each, quickly, since nothing is read for them.
Failures and the delivery log
- Retries. A delivery that fails is retried after 30 seconds, 2 minutes, 10 minutes, 30
minutes, 1 hour, then every hour, from where it stopped. The destination stays
activewhile it retries. - Failing. 24 hours after its first failure, the delivery is
failedand the destinationfailing: no more deliveries are scheduled, and nothing is lost. A store's answer that retrying cannot fix (a redirect,400,401,403or404: a refused credential, a wrong bucket, region or endpoint) makes itfailingat once, without retries. Fix the cause, then resume it: the next delivery starts where the last good one ended and catches everything up. - The delivery log (
GET /v1/destinations/{id}/deliveries, and the destination's page in the app), newest first: each delivery's status (planned,rendering,uploading,done,emptyorfailed), what started it (schedule,run_noworresume), its rows, parts and bytes, its manifest's key, its failed attempts and, when it failed, the store's status and error code verbatim. While it runs,stepsays which part it is on.
Credentials
Every destination writes with one of two kinds of credential; a destination only ever needs to write objects under its prefix.
- Federated (
auth_mode: "federated"; Amazon S3 and Google Cloud Storage): no secret is stored. Your cloud trusts our identity for this one destination: our OpenID Connect issuer ishttps://api.ezyinsights.com(its keys at/oidc/jwks.json), and each token we sign lasts 5 minutes and names the destination as its subject,destination:<id>. We exchange it at your cloud for short-lived credentials and never store them. The setup steps (GET /v1/destinations/{id}/setup, or the app) are filled in with the destination's values: on AWS, an OpenID Connect provider and a role that only this destination may take, allowed onlys3:PutObjectunder the prefix; on Google Cloud, a workload identity provider that trusts only this destination and a service account that may write only under the prefix. Send back the values they give you (federation). S3-compatible stores cannot federate. - Stored (
auth_mode: "stored"): access keys for S3 and S3-compatible stores (s3_keys:access_key_id,secret_access_keyand, when the keys need one,session_token), or a Google Cloud HMAC key (gcs_hmac:access_id,secret). Sent once withPOST /v1/destinations/{id}/credential, sealed (encrypted with a key of its own, which is itself encrypted), and never shown again: the destination shows its kind, its last characters (hint), when it was added and when it was last used. A replacement is tested before it is used; if its test fails, the old credential stays in use.
The test file
A connection test (POST /v1/destinations/{id}/test, or the test on the destination's page in
the app) writes one small file, <prefix>_ezyinsights_test.json, holding
{"destination_id": "dst_…", "at": "…"}, with the destination's credential, and answers the
store's status and error code verbatim when it fails. Each test overwrites it; we never read it,
and you may delete it. At most 10 tests an hour per destination.
Managed legacy feeds
Some agencies receive the hourly JSON layout of an existing feed instead of detection files. Such a
feed is a destination set up by EzyInsights staff, not by you: ask us. You can read it
(GET /v1/destinations lists it, with schema_version legacy) and its delivery log, where each
delivery's parts counts the hourly files it wrote and there is no manifest. Everything else
(changing, testing, pausing, starting or deleting it, and its credential) is for staff: a key gets
403. Its connection test writes the feed's first real hourly file and checks it, never a test
file. Staff may set a test prefix (test_prefix on the destination), so that the connection test
writes that file under the test prefix, beside every feed in the bucket, instead of in one; a test
prefix may not overlap the prefix of any feed in the same bucket, and deliveries never use it.
The newswire-legacy-hourly layout
Your text detections (Newswire matches), one file per hour:
<prefix><YYYY-MM-DD-HH>.json
- The name is the hour's start in the destination's file time zone, on a 24-hour clock. The zone's offset from UTC is a whole number of hours.
- When the clocks go back, the repeated local hour has two files, each name followed by the UTC
offset during that hour. In
Europe/Londonon 25 October 2026:2026-10-25-00.json,2026-10-25-01+0100.json,2026-10-25-01+0000.json,2026-10-25-02.json. - When the clocks go forward, the skipped local hour has no file, and nothing is lost: on 29
March 2026,
2026-03-29-00.jsonis followed by2026-03-29-02.json. - One JSON array per hour, with no whitespace; an hour without matches is
[]. Uncompressed,Content-Type: application/json. Strings are ASCII:/is written\/and every character beyond ASCII as a\uescape, as the original feed wrote them; any JSON parser reads them.
The hour. A file holds the matches scored in that UTC hour, [H, H+1h) by match time, one
object per wire story and article (the hour's latest scoring), sorted by match time, then
story_id, then content_story_id. A match scored again in a later hour appears in that hour's
file too.
The rules, as the original feed applied them; a match is written only when all hold:
- The article's publisher is known.
- The article is not dated before the wire story (an undated article is kept).
- The wire story has two or more sentences (an unknown count is kept).
- The wire story was published within 8 days: on or after 00:00 UTC of the day 8 days before the hour's end. A wire story with no publish time is left out.
Each object, its keys always in this order, null where a value is unknown:
| Field | Type | Meaning |
|---|---|---|
story_id |
integer | Our id for the wire story |
publisher_id |
integer | The publisher's id (a feed that carried the article's id here can be set up to keep doing so) |
to_timestamp |
integer | When the wire story was published: milliseconds since 1970-01-01 UTC |
eid |
string | Your own id for the wire story |
name |
string | The publisher's name |
content_story_id |
integer | The publisher article's id |
syndicated |
boolean | Whether the wire story is syndicated |
content_usage |
string | The band, capitalised: Off, Low, Medium, High or Max (strength.band in the API) |
content_story_sentence_count |
integer | The article's sentence count |
content_story_sentences_matched |
integer | How many of the wire story's sentences the article used, estimated |
language_code |
string | The wire story's language; left out of every object when the feed is set up without it |
canonical_url |
string | The article's canonical URL; null when it could not be resolved |
When files arrive. The feed is checked every 10 minutes. An hour's file is written once all six of its 10-minute export windows have arrived. When a window is still missing 7 hours after the hour ended, the file is written from the windows that have arrived, and written again, under the same name, when the late window arrives. An hour none of whose windows has arrived is not written early: the feed waits, then catches up. On request, staff re-deliver a range of hours; each file is rewritten under its own name.
History. A feed can start at any hour from 2 October 2024. Earlier hours of the feed are built from our historical record of matches, later ones from the export as it arrives.
The imagewire-legacy-hourly layout
Your photo detections (Imagewire matches), one file per hour:
<prefix><YYYY-MM-DD-HH>.json
The name, the two clock changes, the array and its encoding are those of the
newswire-legacy-hourly layout. The file time zone is
Europe/London unless the feed is set up with another.
The hour. A file holds the matches made in that UTC hour, [H, H+1h) by match time, one object
per photo and article, sorted by when the photo's record was created with us, then
imagewire_image_id, then content_story_id. A photo in more than one of your streams is written
once.
The rules, as the original feed applied them; a match is written only when both hold:
- The article's publisher is known.
- The photo was published within 8 days: on or after 00:00 UTC of the day 8 days before the hour's end.
Each object, its keys always in this order, null where a value is unknown:
| Field | Type | Meaning |
|---|---|---|
uri |
string | The photo's source address, as your feed gave it |
eid |
string | Your own id for the photo |
imagewire_image_id |
integer | Our id for the photo |
matched_image |
string | The address of the image found in the publisher's article |
content_story_id |
integer | The publisher article's id |
imagewire_published |
integer | When the photo's record was created with us, milliseconds since 1970-01-01 UTC |
matched_at |
integer | When the match was made, milliseconds since 1970-01-01 UTC |
publisher_name |
string | The publisher's name |
publisher_id |
integer | The publisher's id |
match_score |
string | Low, Medium or High (strength.band in the API) |
imagewire_image |
string | The full picture through our image service, a signed address |
canonical_url |
string | The article's canonical URL; null when it could not be resolved |
When files arrive is as for the text layout: every 10 minutes, an hour once its six export windows have arrived, written from what has arrived 7 hours after the hour ended and again when a late window arrives; staff re-deliver a range of hours on request.
No history. This feed is built from the export as it arrives. A feed can start at any hour from 23 September 2026.
Webhooks
A webhook endpoint receives your new and changed detections as signed POST requests to an
address of yours, minutes after they reach us: for systems that act on a use as it happens rather
than load files. Endpoints are set up in the app under Settings › API › Webhooks, by EzyInsights
staff or an administrator of your subscription, or by code
(Destinations and webhooks by code). A subscription has at
most 10.
- The address: a public
httpsURL of at most 2,048 characters, with a host name (not an IP address), no user name or password and no fragment; a path and a query are yours. Addresses underezyinsights.com,localhostand private names are refused. Redirects are never followed. - Where it starts: a new endpoint receives what reaches us after it is created; nothing earlier is sent.
- One subscription: an endpoint receives only its subscription's detections.
The rule says what an endpoint receives; every field is optional, and all given must hold:
| Field | Rules |
|---|---|
events |
created, updated or both (the default) |
content_types |
text, image or both; only types your subscription carries |
min_band |
This band or stronger, as for a destination's filter (Filters) |
customer |
true: only detections classified licensed; false: only potentially_unlicensed. A detection classified unknown, or not yet classified, matches neither. Refused until your subscription has customers in its Sites list |
domains |
Up to 50 registrable domains, as for a destination's filter |
publisher_ids |
Up to 50 publisher ids. A detection without a publisher never matches |
Messages
Batches. We look for new detections every five minutes. A message holds at most 100 detections, in the order they reached us. An endpoint has one message in flight at a time: the next is made only after your endpoint has accepted the last, and starts where it ended, so messages arrive in order and a backlog arrives message after message.
The body is JSON,
Content-Type: application/json, sent withUser-Agent: EzyInsights-Webhooks/1:{ "type": "detections.batch", "data": [ { "id": "t.9001.5000001.7000001", "version": 2, "event": "updated", "…": "…" } ], "stream_from": { "seq": 18443, "row": 12 }, "stream_to": { "seq": 18444, "row": 3 } }dataholds v1 detections exactly as the change stream gives them,eventincluded (the Detection schema);stream_fromandstream_toare the message's place in your subscription's stream. As on the change stream, a detection version can arrive twice: upsert byid, keeping the higherversion.Your answer. Any
2xxwithin 10 seconds accepts the message; its body is not read. Anything else, a3xxincluded, a timeout or a network error is a failure. Answer first, then process.Retries. A failed message is sent again with the same
webhook-idand the same body after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, then every hour; each attempt carries a newwebhook-timestampand signature. While it retries the endpoint isfailing, and nothing newer is sent behind it; once it is accepted the endpoint isactiveagain.Disabled. 3 days after a message's first failure, the message is
failedand the endpointdisabled: nothing more is sent. Fix your endpoint, then resume it (POST /v1/webhooks/{id}/resume, or the app): it starts where it stopped, and the detections of the failed message are sent again in a new message, with a newwebhook-id.Paused. A paused endpoint gets nothing; a message in flight waits, and its 3-day clock stops until the endpoint is resumed.
The message log (
GET /v1/webhooks/{id}/messages, and the endpoint's page in the app), newest first: each message's kind (batch,testorreplay), detections, status (pending,deliveredorfailed), attempts, your endpoint's last status and response time, the last error, and the next attempt of a pending one.Replay (
POST /v1/webhooks/{id}/messages/{message_id}/replay): a delivered or failed message sent again now, once, with its originalwebhook-idand the same body. It is not retried.The test event (
POST /v1/webhooks/{id}/test): one message holding one obviously fake detection (source.idtest, the publisherExample publisher,eventcreated, anidending in.0.0), signed like any other and sent once, not retried. Tests and replays: at most 10 an hour per endpoint.Rotating the secret (
POST /v1/webhooks/{id}/rotate-secret) answers a new signing secret once. For the next 24 hours every message is signed with both the new and the old secret, so you can switch without losing a message.
Webhook signatures
Every message, retry, replay and test event carries the three headers of the Standard Webhooks convention:
| Header | Value |
|---|---|
webhook-id |
The message's id, msg_…: the same on every retry and replay of a message, so use it to ignore one you have already handled |
webhook-timestamp |
When this attempt was signed, in whole seconds since 1970-01-01 UTC |
webhook-signature |
v1, and the base64 of an HMAC-SHA256; during a secret's 24-hour overlap, two of them separated by a space, the new secret's first |
The secret is whsec_ followed by the base64 of 32 random bytes, answered once when the
endpoint is made and at each rotation. The HMAC key is those 32 bytes: the base64 after whsec_,
decoded. The signed content is the webhook-id, a ., the webhook-timestamp, a . and the body,
exactly as sent: <webhook-id>.<webhook-timestamp>.<body>.
To check a message:
- Use the raw body, the bytes as received, before any JSON parsing: a body parsed and written again does not match.
- Reject an old or future timestamp: we suggest more than 5 minutes from your clock. Each attempt is signed when it is sent, so a retry is never rejected by this.
- Accept the message when any
v1signature in the header matches one you compute with a secret you hold, and compare in constant time.
Node.js:
import { createHmac, timingSafeEqual } from 'node:crypto';
// secret: whsec_…; headers: the request's headers (lower-case names); body: the raw body, as received.
export function verify(secret, headers, body, toleranceSeconds = 300) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
const signatures = headers['webhook-signature'];
if (!id || !timestamp || !signatures) return false;
if (!(Math.abs(Date.now() / 1000 - Number(timestamp)) <= toleranceSeconds)) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key).update(`${id}.${timestamp}.`).update(body).digest();
return signatures.split(' ').some((signature) => {
const [version, value = ''] = signature.split(',');
const given = Buffer.from(value, 'base64');
return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected);
});
}
Python:
import base64, hashlib, hmac, time
def verify(secret, headers, body, tolerance_seconds=300):
"""secret: whsec_…; headers: the request's headers (lower-case names); body: the raw body, bytes."""
msg_id = headers.get("webhook-id")
timestamp = headers.get("webhook-timestamp")
signatures = headers.get("webhook-signature")
if not (msg_id and timestamp and signatures):
return False
try:
if abs(time.time() - int(timestamp)) > tolerance_seconds:
return False
except ValueError:
return False
key = base64.b64decode(secret[len("whsec_"):] if secret.startswith("whsec_") else secret)
signed = f"{msg_id}.{timestamp}.".encode() + body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
return any(
version == "v1" and hmac.compare_digest(value, expected)
for version, _, value in (s.partition(",") for s in signatures.split(" "))
)
Ruby:
require "base64"
require "openssl"
# secret: whsec_…; headers: the request's headers (lower-case names); body: the raw body, as received.
def verify(secret, headers, body, tolerance_seconds = 300)
id = headers["webhook-id"]
timestamp = headers["webhook-timestamp"]
signatures = headers["webhook-signature"]
return false unless id && timestamp && signatures
return false unless timestamp.match?(/\A\d+\z/) && (Time.now.to_i - timestamp.to_i).abs <= tolerance_seconds
key = Base64.strict_decode64(secret.delete_prefix("whsec_"))
signed = "#{id}.#{timestamp}.".b + body.b
expected = Base64.strict_encode64(OpenSSL::HMAC.digest("SHA256", key, signed))
signatures.split(" ").any? do |signature|
version, value = signature.split(",", 2)
version == "v1" && secure_equal?(value.to_s, expected)
end
end
# Constant time for strings of equal length.
def secure_equal?(a, b)
return false unless a.bytesize == b.bytesize
a.bytes.zip(b.bytes).reduce(0) { |acc, (x, y)| acc | (x ^ y) }.zero?
end
Destinations and webhooks by code
Everything the app's Destinations and Webhooks pages do can be done from your own infrastructure
code, a script or a Terraform-style tool, with a key made in the app with Manage destinations
(scope destinations:manage) or Manage webhooks (webhooks:manage). The rules are the same as
in the app, whichever door you use: at most 10 destinations and 10 webhook endpoints per
subscription, at most 10 tests and replays an hour for each (429, Retry-After: 3600), and
bodies of at most 64 KB. Every change is recorded in the app's Activity with the key's name as the
one who made it. A destination or endpoint of another subscription is 404, as an unknown id is.
What a destination writes, and how to read it, is in Deliveries; what an endpoint
receives, and how to check its signatures, in Webhooks and
Webhook signatures.
A destination, from nothing to delivering:
- Create it:
POST /v1/destinations. It starts insetting_up, and nothing is delivered yet. - Set it up at your provider. For a federated destination (no secret stored: your cloud trusts
our identity),
GET /v1/destinations/{id}/setupanswers the steps and policy text filled in with this destination's values, and the fields to send back; send them withPATCH /v1/destinations/{id}asfederation. For stored credentials, send the credential withPOST /v1/destinations/{id}/credential: it is written once to test it, and never shown again. - Test the connection:
POST /v1/destinations/{id}/testanswers the provider's own words. - Start it:
POST /v1/destinations/{id}/resume, once a test has passed.
# 1. Create (Idempotency-Key: a retried timeout creates nothing twice)
curl -s https://api.ezyinsights.com/v1/destinations \
-H "Authorization: Bearer $EZY_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: archive-2026-10" \
-d '{"name": "Archive", "provider": "gcs", "bucket": "agency-archive", "prefix": "ezyinsights/",
"auth_mode": "federated", "format": "jsonl", "compression": "gzip",
"schedule": {"kind": "interval", "minutes": 60}, "start": "now"}'
# 2. The setup steps, then the values they gave you
curl -s https://api.ezyinsights.com/v1/destinations/$ID/setup -H "Authorization: Bearer $EZY_KEY"
curl -s -X PATCH https://api.ezyinsights.com/v1/destinations/$ID \
-H "Authorization: Bearer $EZY_KEY" -H "Content-Type: application/json" -H 'If-Match: "1"' \
-d '{"federation": {"provider_name": "<your provider>", "service_account": "<your service account>"}}'
# 3. Test, 4. start
curl -s -X POST https://api.ezyinsights.com/v1/destinations/$ID/test -H "Authorization: Bearer $EZY_KEY"
curl -s -X POST https://api.ezyinsights.com/v1/destinations/$ID/resume -H "Authorization: Bearer $EZY_KEY"
pause, resume and run-now do what the app's buttons do; resume also restarts a destination
the system stopped after failing, from where it stopped. GET /v1/destinations/{id}/deliveries is
the delivery log, newest first. DELETE stops and deletes a destination; it is 404 afterwards.
Webhooks. POST /v1/webhooks with your endpoint's public https address (and a rule, to
receive less) answers the endpoint with its signing secret, whsec_…, once: store it. Every
message carries webhook-id, webhook-timestamp and webhook-signature (Standard Webhooks); check
the signature with the secret before trusting the body. POST /v1/webhooks/{id}/test sends a
message holding one obviously fake detection; …/messages is the log and
…/messages/{message_id}/replay sends one again. POST /v1/webhooks/{id}/rotate-secret answers a
new secret once, and signs with the old one too for 24 hours, so you can switch without losing a
message.
For tools that converge on a desired state:
- Read, then change.
GETa destination or endpoint and keep itsETag(itsversion, such as"7"); send it asIf-MatchonPATCH,DELETEand the actions. If someone changed it in the app meanwhile, the answer is412with theETagnow, and nothing was done: read it again and decide. WithoutIf-Matchthe last change wins. - Retry safely. Send an
Idempotency-Keyof your own on the creates,rotate-secretandcredential. The same request with the same key within 24 hours answers what the first made, as it is now (or404if it has since been deleted), withIdempotent-Replayed: true; a secret or a test result is never answered twice ("secret": null,"test": null). While the first request still runs, a repeat is409: retry it a moment later. The same key with a different request is422. A refused request, or one with no answer within 5 minutes, leaves the key free. An API key may use 1,000 keys in 24 hours; past that, a new one is429untilRetry-After. - Find what exists. The lists hold at most 10 each, in one page; match on your own
name. - Errors say what to do.
400names the field;409 limit_reachedis a cap;409 state_conflicta state (start before a passed test, a run while one runs);404an id this key cannot see.
Support
Write to support@ezyinsights.com with the X-Request-Id of the
answer you are asking about. Changes to the API are announced in the changelog.
Reference
Every endpoint, generated from openapi.yaml, the OpenAPI 3.1 description of this API.
GET /v1/detections/changes
The change stream
Every new and changed detection in the order it reached the API, to keep a copy in sync. Start with since (a time in the last 31 days) or with the cursor of your last call: exactly one of the two is required, so no client reads from the beginning of time by leaving a parameter out. Every answer carries next_cursor, even when there is nothing new; store it and pass it as cursor next time. A cursor never expires, survives a key roll and is valid with any filter.
A page stops at limit rows or after 50 chunks of the stream have been read, whichever comes first, so a page can hold fewer than limit rows (even none) with has_more: true: keep following next_cursor until has_more is false, then ask again later with the same cursor. When no stream holds anything at or after since, the answer is an empty page whose cursor points at the end of the newest stream, ready to poll.
Delivery is at least once: upsert by id and keep the higher version. Each detection here carries event (created or updated). A request reads at most 20 streams, one per content type of the key's subscription (so at most two today). The rows returned count against the daily row allowance.
Authentication: A key or an access token (Authorization: Bearer …) with the scope detections:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cursor | query | StreamCursor | no | The next_cursor of a previous answer from this endpoint. Exclusive with since. A value this endpoint did not give is 400. |
since | query | string (date-time) | no | Start at the first change delivered at or after this time. An ISO 8601 time with Z or an offset (2026-09-24T10:00:00Z, 2026-09-24T12:00:00+02:00, optional milliseconds), not in the future and at most 31 days (31 × 24 hours) ago; older history is read with GET /v1/detections. Exclusive with cursor. |
limit | query | integer | no | The most rows to return. 1 to 1,000; default 100 |
subscription_id | query | integer | no | Optional and not repeatable: a key reads exactly its own subscription (/v1/me), which may be named here. Any other id is 400 with the same text whether it exists or not ("subscription 1234 is not available to this key").1 to 999,999,999,999,999 |
content_type | query | string | no | Only this content type. It must be one the key can read; unset means every type in its scope. one of text, image |
publisher_id | query | array of integer | no | Only detections in articles of these publishers (article.publisher.id). Repeatable or comma-separated; at most 50 values. A detection without a publisher never matches.at most 50 values; each 1 to 999,999,999,999,999 |
exclude_publisher_id | query | array of integer | no | Every publisher except these. Repeatable or comma-separated; at most 50 values. A detection without a publisher is kept. at most 50 values; each 1 to 999,999,999,999,999 |
domain | query | array of string | no | Only detections in articles on these domains (article.domain). Repeatable or comma-separated; at most 20 values. Each is a domain (example-daily.test) or an http(s) URL with no path; it is compared in lower case and punycode, so münchen.example and xn--mnchen-3ya.example are the same. A path, port, query, fragment or user name is 400.at most 20 values |
exclude_domain | query | array of string | no | Every domain except these, written as for domain. Repeatable or comma-separated; at most 20 values. A detection without a domain is kept.at most 20 values |
min_band | query | string | no | Only detections at this band or stronger. Text bands run off < low < medium < high < max; image bands low < medium < high, and the same word means the same step for both types. So min_band=off keeps everything, min_band=low drops text off, and min_band=max keeps only text max and excludes every image.one of off, low, medium, high, max |
band | query | array of string | no | Exactly these bands (band=medium&band=high or band=medium,high). Repeatable or comma-separated. off and max match no image.each one of off, low, medium, high, max |
min_score | query | integer | no | Only detections whose strength.score, rounded to a whole number, is at least this: the usage percentage for text (0–100), the match score for images (0–99).0 to 100 |
print | query | boolean | no | true for print articles only, false for everything else. Image detections are never print. |
source_id | query | string | no | Only detections of this agency item (source.id, the agency's own id), exactly as written.at most 200 characters |
article_id | query | integer | no | Only detections in this publisher article (article.id).1 to 999,999,999,999,999 |
fields | query | string | no | Return only these fields: a comma-separated list of paths from the detection schema (fields=first_detected_at,strength,article.url,article.publisher). A path is a field (article.url) or an object holding some (strength, article.publisher), returned whole. id and version are always returned; the fields keep the detection's order; a field the detection's content type does not have stays absent. An unknown path is 400. |
schema_version | query | string | no | The detection schema version. v1, the default, is the only one.one of v1; default v1 |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | A page of the stream. | application/json: ChangesPage | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited as on every authenticated endpoint (the rate-limit headers only when the credential was verified), or daily_allowance: the key or its subscription has used its daily row allowance. The detail gives the reset (the next 00:00 UTC) and Retry-After the seconds until then. The cursor you hold stays valid. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (ChangesPage)
| Field | Type | Nullable | Description |
|---|---|---|---|
data | array of Detection | no | The detections, in the order they reached the API, each with event. |
next_cursor | StreamCursor | no | A position in the change stream, opaque (base64url). Valid with any filter, never expires and survives a key roll. |
has_more | boolean | no | True to call again now with next_cursor; false when caught up (call again later with it). |
as_of | string (date-time) or null | yes | The data is complete up to this time: the end of the newest finished export window, the earliest over the content types read. Null while an export has none. |
GET /v1/detections
Detections first detected in a period
The current state of every detection whose first_detected_at falls in a period of at most 31 days, filtered, sorted by first detection and paged with a query cursor. from is inclusive and to exclusive; a date-only value is read in the request's time zone, and a date-only to includes its whole day (from=2026-09-23&to=2026-09-23 is one day). The zone is time_zone if given, else the subscription's own when the request resolves to exactly one subscription, else UTC. A to in the future is read as now. The answer echoes the resolved from, to and time_zone.
The period may be at most 31 days: 31 calendar days when from and to are both dates, otherwise 31 × 24 hours and one more hour (for a clock change) between the two times. from may not be earlier than the day records begin (the earliest data_starts in /v1/me of the requested streams, that day's start in the request's time zone). Longer periods are walked month by month.
The period and the filters are fixed for a whole walk: the cursor carries a hash of them, and a cursor used with a changed request is refused with 400 ("the period or filters changed; start again"). limit may change between pages.
A period that ended less than two days ago is still filling, and a walk through it is not a consistent snapshot. Detections here carry no event, which belongs to the change stream. A request reads the key's one subscription, and a request whose period reaches more than 64 shards of storage is 400 ("narrow the period or the subscriptions"). The rows returned count against the daily row allowance.
Authentication: A key or an access token (Authorization: Bearer …) with the scope detections:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string | yes | The period's start, inclusive: a date (YYYY-MM-DD, that day's start in the request's time zone) or an ISO 8601 time with Z or an offset. |
to | query | string | yes | The period's end, exclusive: a date (the end of that day in the request's time zone, so the day is included) or an ISO 8601 time with Z or an offset. Later than from. A future value is read as now. |
time_zone | query | string | no | An IANA time zone name (Europe/Berlin) for reading date-only from and to. Default: the subscription's own time zone when the request resolves to one subscription, else UTC. Echoed as written. |
sort | query | string | no | Newest first (the default) or oldest first, by first_detected_at, then by id.one of -first_detected_at, first_detected_at; default -first_detected_at |
limit | query | integer | no | The most rows to return: up to 1,000 when the request covers one (subscription, content type) stream, up to 200 when it covers more. 1 to 1,000; default 100 |
cursor | query | QueryCursor | no | The next_cursor of the previous page of the same request. A cursor used with a changed period, time zone, sort or filters is 400. |
subscription_id | query | integer | no | Optional and not repeatable: a key reads exactly its own subscription (/v1/me), which may be named here. Any other id is 400 with the same text whether it exists or not ("subscription 1234 is not available to this key").1 to 999,999,999,999,999 |
content_type | query | string | no | Only this content type. It must be one the key can read; unset means every type in its scope. one of text, image |
publisher_id | query | array of integer | no | Only detections in articles of these publishers (article.publisher.id). Repeatable or comma-separated; at most 50 values. A detection without a publisher never matches.at most 50 values; each 1 to 999,999,999,999,999 |
exclude_publisher_id | query | array of integer | no | Every publisher except these. Repeatable or comma-separated; at most 50 values. A detection without a publisher is kept. at most 50 values; each 1 to 999,999,999,999,999 |
domain | query | array of string | no | Only detections in articles on these domains (article.domain). Repeatable or comma-separated; at most 20 values. Each is a domain (example-daily.test) or an http(s) URL with no path; it is compared in lower case and punycode, so münchen.example and xn--mnchen-3ya.example are the same. A path, port, query, fragment or user name is 400.at most 20 values |
exclude_domain | query | array of string | no | Every domain except these, written as for domain. Repeatable or comma-separated; at most 20 values. A detection without a domain is kept.at most 20 values |
min_band | query | string | no | Only detections at this band or stronger. Text bands run off < low < medium < high < max; image bands low < medium < high, and the same word means the same step for both types. So min_band=off keeps everything, min_band=low drops text off, and min_band=max keeps only text max and excludes every image.one of off, low, medium, high, max |
band | query | array of string | no | Exactly these bands (band=medium&band=high or band=medium,high). Repeatable or comma-separated. off and max match no image.each one of off, low, medium, high, max |
min_score | query | integer | no | Only detections whose strength.score, rounded to a whole number, is at least this: the usage percentage for text (0–100), the match score for images (0–99).0 to 100 |
print | query | boolean | no | true for print articles only, false for everything else. Image detections are never print. |
source_id | query | string | no | Only detections of this agency item (source.id, the agency's own id), exactly as written.at most 200 characters |
article_id | query | integer | no | Only detections in this publisher article (article.id).1 to 999,999,999,999,999 |
fields | query | string | no | Return only these fields: a comma-separated list of paths from the detection schema (fields=first_detected_at,strength,article.url,article.publisher). A path is a field (article.url) or an object holding some (strength, article.publisher), returned whole. id and version are always returned; the fields keep the detection's order; a field the detection's content type does not have stays absent. An unknown path is 400. |
schema_version | query | string | no | The detection schema version. v1, the default, is the only one.one of v1; default v1 |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | A page of the period. | application/json: RangePage | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited as on every authenticated endpoint (the rate-limit headers only when the credential was verified), or daily_allowance: the key or its subscription has used its daily row allowance. The detail gives the reset (the next 00:00 UTC) and Retry-After the seconds until then. The cursor you hold stays valid. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (RangePage)
| Field | Type | Nullable | Description |
|---|---|---|---|
data | array of Detection | no | The detections' current states, in the requested sort, without event. |
next_cursor | QueryCursor or any or null | yes | The next page's cursor, or null when the period is read. |
has_more | boolean | no | True when there may be another page (which can be empty). |
from | string (date-time) | no | The period's start as resolved, inclusive. |
to | string (date-time) | no | The period's end as resolved, exclusive (now, if to was in the future). |
time_zone | string | no | The time zone the period was read in. |
as_of | string (date-time) or null | yes | As on the change stream. |
GET /v1/detections/{id}
One detection
The detection, latest version, including the latest last_scored_at. Without event, which belongs to the change stream. An id that is well formed but unknown, or that names a subscription or content type outside the key's scope, is 404, never 403. The row returned counts against the daily row allowance.
Authentication: A key or an access token (Authorization: Bearer …) with the scope detections:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | The detection's id: <t|i>.<subscription>.<source internal id>.<article id>. Anything else is 400.pattern ^[ti]\.(0|[1-9][0-9]{0,14})\.(0|[1-9][0-9]{0,14})\.(0|[1-9][0-9]{0,14})$ |
fields | query | string | no | Return only these fields: a comma-separated list of paths from the detection schema (fields=first_detected_at,strength,article.url,article.publisher). A path is a field (article.url) or an object holding some (strength, article.publisher), returned whole. id and version are always returned; the fields keep the detection's order; a field the detection's content type does not have stays absent. An unknown path is 400. |
schema_version | query | string | no | The detection schema version. v1, the default, is the only one.one of v1; default v1 |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The detection. | application/json: Detection | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: there is no endpoint at this path (a trailing slash never matches), or nothing with this id in the key's scope: no such detection, or no used item at /v1/sources/{content_type}/{internal_id} (an item that is unknown, never used or another subscription's reads the same). The rate-limit headers are sent only with the second, when the credential was verified. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited as on every authenticated endpoint (the rate-limit headers only when the credential was verified), or daily_allowance: the key or its subscription has used its daily row allowance. The detail gives the reset (the next 00:00 UTC) and Retry-After the seconds until then. The cursor you hold stays valid. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
GET /v1/detections/{id}/evidence
How a text detection was matched
The record of how one text detection was matched, read from the matcher's own records while EzyInsights keeps them: 45 days after matched_at (the detection's last_scored_at), when evidence.expires_at passes. The publisher's article and your story sentence by sentence, each of their sentences with your nearest and how alike the two are (0 to 1), the usage counted at three levels, and how often the pair was matched. evidence.article_text says whether the publisher's whole article is carried (whole: a customer's publisher, or usage from medium up) or only the matched passages (matched: sentences under 0.65 carry no text). What you download is yours to keep; from expires_at on this answers 410.
An id outside the key's scope, or unknown, is 404 not_found, as for the detection itself, and nothing is read for it. An image detection is 404 evidence_not_available: image evidence comes later. A print use is 404 evidence_missing (no page was collected). A use whose record is not found yet while its match is under two hours old answers 200 with status: pending; after that 404 evidence_missing. A use taken down on a legal request answers 200 with status: suppressed and no texts. A failure to read the records is 503 evidence_unavailable, with Retry-After when retrying can help. Each answer counts as one row of the daily row allowance.
Authentication: A key or an access token (Authorization: Bearer …) with the scope detections:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | The detection's id: <t|i>.<subscription>.<source internal id>.<article id>. Anything else is 400.pattern ^[ti]\.(0|[1-9][0-9]{0,14})\.(0|[1-9][0-9]{0,14})\.(0|[1-9][0-9]{0,14})$ |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The record, or a use pending or suppressed. | application/json: TextEvidenceAnswer | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no detection with this id in the key's scope (nothing is read). Or evidence_missing: no record of how it was matched exists (a print use, or none found more than two hours after the match). Or evidence_not_available: an image detection, whose evidence comes later. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 410 | evidence_gone: the record was kept until expires_at, 45 days after the match, and is no longer kept. It will not come back. | application/problem+json: EvidenceGoneProblem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 429 | rate_limited as on every authenticated endpoint (the rate-limit headers only when the credential was verified), or daily_allowance: the key or its subscription has used its daily row allowance. The detail gives the reset (the next 00:00 UTC) and Retry-After the seconds until then. The cursor you hold stays valid. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | evidence_unavailable: the record could not be read just now; Retry-After when retrying can help. Or unavailable, as on every endpoint. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (TextEvidenceAnswer)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The detection's id. |
evidence | TextEvidenceRecord | no | The envelope, the use's own facts, and (when status is stored) the record: matched, recorded, usage, story and article. matched_at and expires_at are the record's own (the evaluation shown, the same second as the detection's when matched.exact). |
evidence.kind | string | no | always text |
evidence.status | string | no | pending: no record yet, the match under two hours old. suppressed: taken down on a legal request; no texts. gone, missing and unreadable (the record exists but can never be used: unparseable, over its cap, or naming another pair; no texts) appear in a side file; /evidence answers the first two as problems.one of stored, pending, missing, gone, suppressed, unreadable |
evidence.matched_at | string (date-time) | no | |
evidence.expires_at | string (date-time) | no | |
evidence.article_text | string | no | one of whole, matched |
evidence.record | string (uri) | no | |
evidence.pack | string (uri) | no | |
evidence.use | object | no | The use's own facts, from the detection. |
evidence.use.publisher optional | object | no | |
evidence.use.publisher.id optional | integer or null | yes | |
evidence.use.publisher.name optional | string or null | yes | |
evidence.use.article optional | object | no | |
evidence.use.article.id optional | integer | no | |
evidence.use.article.url optional | string or null | yes | |
evidence.use.article.domain optional | string or null | yes | |
evidence.use.article.headline optional | string or null | yes | |
evidence.use.article.published_at optional | string (date-time) or null | yes | |
evidence.use.story optional | object | no | |
evidence.use.story.id optional | integer | no | |
evidence.use.story.headline optional | string or null | yes | |
evidence.use.story.published_at optional | string (date-time) or null | yes | |
evidence.use.print optional | boolean | no | |
evidence.use.matched_at optional | string (date-time) | no | |
evidence.use.usage optional | number or null | yes | |
evidence.use.band optional | string or null | yes | |
evidence.use.matched_sentences optional | integer or null | yes | |
evidence.use.story_sentences optional | integer or null | yes | |
evidence.use.article_sentences optional | integer or null | yes | |
evidence.use.classification optional | string or null | yes | |
evidence.matched optional | object | no | Every evaluation of the pair the matcher's records hold; exact is false when none reproduced the detection's recorded usage near its matched_at and another is shown. |
evidence.matched.count optional | integer | no | |
evidence.matched.latest_at optional | string (date-time) | no | |
evidence.matched.first_at optional | string (date-time) | no | |
evidence.matched.first_usage optional | number or null | yes | |
evidence.matched.first_article_sentences optional | integer or null | yes | |
evidence.matched.exact optional | boolean | no | |
evidence.recorded optional | object | no | The detection's own usage, as recorded. |
evidence.recorded.usage optional | number | no | |
evidence.recorded.at optional | string (date-time) | no | |
evidence.usage optional | object | no | Usage counted from the pairs at similarity 0.65, 0.80 and 0.95, each similarity and percentage rounded half up: at_80 is the product's usage. |
evidence.usage.at_65 optional | integer | no | |
evidence.usage.at_80 optional | integer | no | |
evidence.usage.at_95 optional | integer | no | |
evidence.story optional | object | no | Your story, the version the match saw. |
evidence.story.id optional | integer | no | |
evidence.story.version_id optional | integer | no | |
evidence.story.version_number optional | integer | no | |
evidence.story.versions optional | integer | no | |
evidence.story.published_at optional | string (date-time) or null | yes | |
evidence.story.is_newest optional | boolean | no | |
evidence.story.sentence_count optional | integer | no | |
evidence.story.sentences optional | array of string or null | yes | Your version's sentences as matched; null when that version was not kept (each pair then carries nearest_text). |
evidence.story.paragraph_starts optional | array of integer or null | yes | |
evidence.article optional | object | no | The publisher's article as collected for this match, a sentence an entry, in order. |
evidence.article.id optional | integer | no | |
evidence.article.publisher optional | object or null | yes | |
evidence.article.publisher.id optional | integer | yes | |
evidence.article.publisher.name optional | string or null | yes | |
evidence.article.publisher.is_customer optional | boolean or null | yes | |
evidence.article.url optional | string or null | yes | |
evidence.article.print optional | boolean | no | |
evidence.article.collected_at optional | string (date-time) | no | |
evidence.article.sentence_count optional | integer | no | |
evidence.article.paragraph_starts optional | array of integer or null | yes | |
evidence.article.sentences optional | array of object | no | |
evidence.article.sentences[].n | integer | no | Their sentence's number. |
evidence.article.sentences[].text optional | string | no | Absent for a sentence under 0.65 when article_text is matched. |
evidence.article.sentences[].nearest | integer | no | Your nearest sentence's number. |
evidence.article.sentences[].similarity | number | no | 0 to 1 |
evidence.article.sentences[].nearest_text optional | string | no | Your nearest sentence as quoted, only when story.sentences is null. |
evidence.article.not_shown optional | object or null | yes | When sentences were left out (matched), how many and where. |
evidence.article.not_shown.count optional | integer | yes | |
evidence.article.not_shown.runs optional | array of object | yes | |
evidence.article.not_shown.runs[].from optional | integer | no | |
evidence.article.not_shown.runs[].to optional | integer | no |
GET /v1/detections/{id}/evidence/pack
How a text detection was matched, as a ZIP
The same record as a ZIP to keep: README.txt (what it is, and the marks), how-it-was-matched.html (the comparison as a page you can open or print), their-article.txt and your-story.txt (a sentence a line, numbered), evidence.json (the record) and detection.json (the use). It carries what article_text allows. A print, pending, missing or suppressed use's ZIP holds README.txt (why) and detection.json only. Streamed as it is made and stored nowhere; never cached. From expires_at on, 410. The same scope and refusals as /v1/detections/{id}/evidence; one row of the daily row allowance.
Authentication: A key or an access token (Authorization: Bearer …) with the scope detections:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | The detection's id: <t|i>.<subscription>.<source internal id>.<article id>. Anything else is 400.pattern ^[ti]\.(0|[1-9][0-9]{0,14})\.(0|[1-9][0-9]{0,14})\.(0|[1-9][0-9]{0,14})$ |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The ZIP, as an attachment named evidence-<id>.zip. | application/zip: string (binary) | X-Request-Id, Cache-Control, Content-Disposition, X-Content-Type-Options, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no detection with this id in the key's scope (nothing is read). Or evidence_missing: no record of how it was matched exists (a print use, or none found more than two hours after the match). Or evidence_not_available: an image detection, whose evidence comes later. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 410 | evidence_gone: the record was kept until expires_at, 45 days after the match, and is no longer kept. It will not come back. | application/problem+json: EvidenceGoneProblem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 429 | rate_limited as on every authenticated endpoint (the rate-limit headers only when the credential was verified), or daily_allowance: the key or its subscription has used its daily row allowance. The detail gives the reset (the next 00:00 UTC) and Retry-After the seconds until then. The cursor you hold stays valid. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | evidence_unavailable: the record could not be read just now; Retry-After when retrying can help. Or unavailable, as on every endpoint. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body
| Field | Type | Nullable | Description |
|---|
GET /v1/me
The key and its subscription
Who the credential is, and everything about its subscription a client needs: its time zone, where each stream's records begin (data_starts), the export gaps of the last 90 days (data_gaps) and the subscription's limits, with whether the key or the subscription is throttled by the daily row allowance. A key reads exactly one subscription, the one it was created for, and nothing here names any other. Any valid key or token, whatever its scopes; it keeps working while the daily row allowance is used. Cheap to call: its answer is cached for up to a minute.
Authentication: A key or an access token (Authorization: Bearer …), any scope.
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The key, its subscription and the limits. | application/json: Me | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Me)
| Field | Type | Nullable | Description |
|---|---|---|---|
key | object | no | |
key.id | string | no | The key id (the 12 characters after ezy_live_). |
key.name | string | no | The key's name. |
key.scopes | array of string | no | The scopes this credential has now (for a token, those it was issued with that the key still has). |
key.expires_at | string (date-time) or null | yes | When the key expires; null if it does not. |
subscription | object | no | The key's subscription, the only one it reads. |
subscription.id | integer | no | The subscription id, as detections carry it. |
subscription.name | string or null | yes | The subscription's name. |
subscription.content_types | array of string | no | The content types our exports carry for it; empty until they name it. each one of text, image |
subscription.time_zone | string | no | The subscription's IANA time zone, used for date-only periods. |
subscription.data_starts | object | no | Per content type, where the stream's records begin; null while it has none. /v1/detections refuses a from before that day (before rows_start once a subscription's history is loaded: counts reach back to data_starts, detections to rows_start). |
subscription.data_starts.text optional | string (date-time) or null | yes | |
subscription.data_starts.image optional | string (date-time) or null | yes | |
subscription.customer_lists | boolean | no | Whether the subscription has a Sites list (GET /v1/subscriptions/{id}/sites), the list its detections' customer and classification come from. |
subscription.classification_since | string (date-time) or null | yes | When the subscription's Sites list first existed: detections created or re-scored since then carry customer and classification; older ones have customer: null. Null while it has no list. |
subscription.history_until optional | object | no | Present only once the subscription's history is loaded (its two-year history snapshot, per subscription): per content type, the time before which its counts come from that snapshot, the line where our own records begin; null for a content type without history (images). Absent until then, and data_starts is where the records begin. See "History counts" in the guide. |
subscription.history_until.text optional | string (date-time) or null | yes | |
subscription.history_until.image optional | string (date-time) or null | yes | |
subscription.rows_start optional | object | no | Present with history_until: per content type, where the detections themselves begin (GET /v1/detections refuses a from before that day). Counts reach back to data_starts; the detections before rows_start are counted, not served. |
subscription.rows_start.text optional | string (date-time) or null | yes | |
subscription.rows_start.image optional | string (date-time) or null | yes | |
data_gaps | object | no | Per content type in the key's scope, export windows of the last 90 days whose file has not arrived (missing), was given up (abandoned) or could not be read (failed), newest first, at most 200 each. A window listed here has contributed no detections, whatever happened in it. |
data_gaps.text optional | array of Gap | no | |
data_gaps.text[].window_start | string (date-time) | no | The start of the 10-minute export window. |
data_gaps.text[].status | string | no | missing: the window's file has not arrived, a day after it was due; it is still looked for once a day, and if it arrives its detections reach the change stream then. abandoned: missing for 30 days and no longer looked for. failed: the file arrived but could not be read, and stays so until we reset it; its detections reach the change stream if it is then read.one of missing, abandoned, failed |
data_gaps.image optional | array of Gap | no | |
data_gaps.image[].window_start | string (date-time) | no | The start of the 10-minute export window. |
data_gaps.image[].status | string | no | missing: the window's file has not arrived, a day after it was due; it is still looked for once a day, and if it arrives its detections reach the change stream then. abandoned: missing for 30 days and no longer looked for. failed: the file arrived but could not be read, and stays so until we reset it; its detections reach the change stream if it is then read.one of missing, abandoned, failed |
limits | object | no | |
limits.requests_per_minute | integer | no | Requests a minute per key. |
limits.daily_rows | integer | no | The subscription's daily row allowance for detection reads. |
limits.daily_file_rows | integer | no | The subscription's daily row allowance for files: every delivery's rows count against it, and a destination whose first delivery would pass what is left of it today is refused. |
limits.exports_per_day | integer | no | Exports the subscription may create a day (from a later version). |
limits.throttled | string or null | yes | Whether the key or the whole subscription is throttled by the daily row allowance. one of key, subscription |
limits.throttled_until optional | string (date-time) | no | When the throttle ends (the next 00:00 UTC); present only while throttled. |
schema_version | string | no | The detection schema version answers use by default. one of v1 |
GET /v1/schema/detection
The v1 detection, machine-readable
Every field of the detection, in the order a detection is written: its dotted path, the flat column name used by files (dots become underscores), its position, type, nullability, the content types that carry it and a description. Any valid key or token. The answer carries an ETag and Cache-Control: no-cache; send the ETag back in If-None-Match and an unchanged schema is 304 with no body.
Authentication: A key or an access token (Authorization: Bearer …), any scope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
schema_version | query | string | no | The detection schema version. v1, the default, is the only one.one of v1; default v1 |
If-None-Match | header | string | no | An ETag from an earlier answer (or a list of them, or *). |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The schema. | application/json: Schema | X-Request-Id, ETag, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 304 | Not modified; If-None-Match named the current ETag. No body. | none | X-Request-Id, ETag, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Schema)
| Field | Type | Nullable | Description |
|---|---|---|---|
schema_version | string | no | one of v1 |
fields | array of SchemaField | no | |
fields[].path | string | no | The dotted path in the JSON detection. |
fields[].column | string | no | The flat column name for files; dots become underscores. |
fields[].position | integer | no | 1-based position in the column list. |
fields[].type | string | no | timestamp is an ISO 8601 UTC time with whole seconds and Z.one of string, integer, number, boolean, timestamp |
fields[].nullable | boolean | no | |
fields[].content_types | array of string | no | The content types that carry the field. each one of text, image |
fields[].description | string | no |
HEAD /v1/schema/detection
The schema's headers only
As GET, with the same status and headers and no body.
Authentication: A key or an access token (Authorization: Bearer …), any scope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
schema_version | query | string | no | The detection schema version. v1, the default, is the only one.one of v1; default v1 |
If-None-Match | header | string | no | An ETag from an earlier answer (or a list of them, or *). |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | As GET, without the body. | none | X-Request-Id, ETag, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 304 | Not modified. | none | X-Request-Id, ETag, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| default | As GET, without the body. | none |
POST /oauth/token
An access token for a key
OAuth 2.0 client credentials (RFC 6749 §4.4). The client is an API key: its id as client_id and its secret as client_secret, either in the form body or as HTTP Basic (Authorization: Basic base64(<key id>:<secret>)), not both. As a convenience, the whole key (ezy_live_…) is also accepted as client_secret when its id matches client_id. The token lasts one hour; request a new one when it expires. Its scopes are the ones asked for in scope (a subset of the key's), or all of the key's; on every request they are intersected with the key's current scopes, and revoking the key stops its tokens within a minute.
Errors are RFC 6749's { "error", "error_description" }, except a body over 4 KiB (413), the rate limit (429) and a service fault (500, 503), which are problem documents. At most 10 requests a minute per client id and per address. The body is at most 4,096 bytes and no parameter may be given twice.
Authentication: None.
Request body
As application/x-www-form-urlencoded:
| Field | Type | Required | Description |
|---|---|---|---|
grant_type | string | yes | one of client_credentials |
client_id | string | no | The key id. Omit when sending HTTP Basic credentials. pattern ^[a-z2-7]{12}$ |
client_secret | string | no | The key's secret (the 52 characters after the key id), or the whole key when its id matches client_id. Omit when sending HTTP Basic credentials. |
scope | string | no | Space-separated scopes, a subset of the key's. Omitted or empty: all of the key's scopes. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The access token. | application/json: Token | X-Request-Id, Cache-Control, Pragma |
| 400 | invalid_request (not a form, a parameter given twice, credentials both in the body and as Basic, malformed Basic credentials), unsupported_grant_type (grant_type is not client_credentials) or invalid_scope (a scope the key does not have). | application/json: OAuthError | X-Request-Id, Cache-Control, Pragma |
| 401 | invalid_client: the client credentials are not valid, or the key may not be used (revoked, expired, its subscription's API suspended, address not allowed). With HTTP Basic, the answer carries WWW-Authenticate: Basic realm="ezy-data". | application/json: OAuthError | X-Request-Id, Cache-Control, Pragma, WWW-Authenticate |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 413 | content_too_large: the body is larger than 4 KiB. | application/problem+json: Problem | X-Request-Id, Cache-Control |
| 429 | rate_limited: more than 10 token requests a minute for this client or this address, or too many requests with unknown key ids from this address. Retry after the seconds in Retry-After. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Token)
| Field | Type | Nullable | Description |
|---|---|---|---|
access_token | string | no | Send as Authorization: Bearer <access_token>. |
token_type | string | no | one of Bearer |
expires_in | integer | no | Seconds the token lasts (3,600). |
scope | string | no | The token's scopes, space-separated. |
GET /v1/health
Whether the data is current
No authentication and no rate limit. 200 with status: ok while no alert that needs someone is open; otherwise 503 with status: degraded and the same body. The alert customers meet most is ingest stalled: it opens when an export's newest finished window ended more than 45 minutes ago (checked every five minutes), so health turns 503 about 45 to 50 minutes after the last finished window; an export with no finished window at all, or one older than an hour, is 503 as well. While ingest is deliberately paused (for maintenance, shown as alerts.paused: 1), the windows' age is not judged, so a pause alone keeps 200. newest_done is the end of each export's newest finished window, the same value as_of is built from; alerts gives counts only.
Authentication: None.
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | Both exports are current. | application/json: Health | X-Request-Id, Cache-Control |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | Degraded: an alert that needs someone is open (alerts.page_worthy above 0; ingest stalled opens 45 minutes after an export's newest finished window ended), or, unless ingest is paused, an export's newest finished window ended more than an hour ago or it has none (newest_done: null). The body is a Health document, not a problem. | application/json: Health | X-Request-Id, Cache-Control |
200 body (Health)
| Field | Type | Nullable | Description |
|---|---|---|---|
status | string | no | one of ok, degraded |
exports | object | no | Per export (newswire for text, imagewire for images). Our own inputs for sites (subscription_customers, publishers, publisher_collection) and for access (subscription_status) are listed once they have started; they never make health 503. |
exports.newswire | ExportHealth | no | |
exports.newswire.newest_done | string (date-time) or null | yes | The end of the newest finished window; null when there is none. |
exports.imagewire | ExportHealth | no | |
exports.imagewire.newest_done | string (date-time) or null | yes | The end of the newest finished window; null when there is none. |
exports.subscription_customers optional | ExportHealth | no | |
exports.subscription_customers.newest_done | string (date-time) or null | yes | The end of the newest finished window; null when there is none. |
exports.subscription_status optional | ExportHealth | no | |
exports.subscription_status.newest_done | string (date-time) or null | yes | The end of the newest finished window; null when there is none. |
exports.publishers optional | ExportHealth | no | |
exports.publishers.newest_done | string (date-time) or null | yes | The end of the newest finished window; null when there is none. |
exports.publisher_collection optional | ExportHealth | no | |
exports.publisher_collection.newest_done | string (date-time) or null | yes | The end of the newest finished window; null when there is none. |
alerts | object | no | Our operational alerts, as counts only. |
alerts.open | integer | no | Alerts open now. at least 0 |
alerts.page_worthy | integer | no | Open alerts that need someone now (ingest stalled, undeliverable ingest messages, API errors). Above 0, health is 503.at least 0 |
alerts.paused | integer | no | 1 while ingest is deliberately paused, else 0. A pause alone does not make health 503.0 to 1 |
HEAD /v1/health
Health's status only
As GET, with the same status and headers and no body.
Authentication: None.
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | Both exports are current. | none | X-Request-Id, Cache-Control |
| 503 | Degraded. | none | X-Request-Id, Cache-Control |
GET /.well-known/openid-configuration
The issuer's discovery document
No authentication and no rate limit. The OpenID Connect discovery document of the issuer https://api.ezyinsights.com, which AWS, Google Cloud and Azure read when you trust it for a push destination. The identity tokens it signs are ES256 JWTs (typ: JWT) with the subject destination:<id> and an audience per cloud, valid for 5 minutes; they are not access tokens for this API and are never accepted by it. Cacheable for an hour. 404 while the issuer is not configured.
Authentication: None.
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The discovery document. | application/json: OpenIdConfiguration | X-Request-Id, Cache-Control |
| 404 | not_found: there is no endpoint at this path (a trailing slash never matches), or nothing with this id in the key's scope: no such detection, or no used item at /v1/sources/{content_type}/{internal_id} (an item that is unknown, never used or another subscription's reads the same). The rate-limit headers are sent only with the second, when the credential was verified. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
200 body (OpenIdConfiguration)
| Field | Type | Nullable | Description |
|---|---|---|---|
issuer | string | no | The issuer, the iss of every identity token.always https://api.ezyinsights.com |
jwks_uri | string | no | Where the public keys are. always https://api.ezyinsights.com/oidc/jwks.json |
response_types_supported | array of string | no | each one of id_token |
subject_types_supported | array of string | no | each one of public |
id_token_signing_alg_values_supported | array of string | no | each one of ES256 |
claims_supported | array of string | no | each one of sub, aud, exp, iat, iss, jti |
HEAD /.well-known/openid-configuration
The discovery document's status only
As GET, with the same status and headers and no body.
Authentication: None.
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The discovery document exists. | none | X-Request-Id, Cache-Control |
| 404 | not_found: there is no endpoint at this path (a trailing slash never matches), or nothing with this id in the key's scope: no such detection, or no used item at /v1/sources/{content_type}/{internal_id} (an item that is unknown, never used or another subscription's reads the same). The rate-limit headers are sent only with the second, when the credential was verified. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
GET /oidc/jwks.json
The issuer's public keys
No authentication and no rate limit. The public keys that verify the issuer's identity tokens, as a JSON Web Key Set: P-256 keys for ES256, each with its kid (its RFC 7638 thumbprint). The set holds every key in use: a new key is published before it signs, and an old one stays until tokens it signed have expired. Cacheable for an hour. 404 while the issuer is not configured.
Authentication: None.
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The key set. | application/json: JsonWebKeySet | X-Request-Id, Cache-Control |
| 404 | not_found: there is no endpoint at this path (a trailing slash never matches), or nothing with this id in the key's scope: no such detection, or no used item at /v1/sources/{content_type}/{internal_id} (an item that is unknown, never used or another subscription's reads the same). The rate-limit headers are sent only with the second, when the credential was verified. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
200 body (JsonWebKeySet)
| Field | Type | Nullable | Description |
|---|---|---|---|
keys | array of JsonWebKey | no | |
keys[].kty | string | no | always EC |
keys[].crv | string | no | always P-256 |
keys[].x | string | no | The x coordinate, base64url. |
keys[].y | string | no | The y coordinate, base64url. |
keys[].use | string | no | always sig |
keys[].alg | string | no | always ES256 |
keys[].kid | string | no | The key's id, its RFC 7638 thumbprint (SHA-256, base64url). |
HEAD /oidc/jwks.json
The key set's status only
As GET, with the same status and headers and no body.
Authentication: None.
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The key set exists. | none | X-Request-Id, Cache-Control |
| 404 | not_found: there is no endpoint at this path (a trailing slash never matches), or nothing with this id in the key's scope: no such detection, or no used item at /v1/sources/{content_type}/{internal_id} (an item that is unknown, never used or another subscription's reads the same). The rate-limit headers are sent only with the second, when the credential was verified. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
GET /v1/sources
Your items that were used, with their totals
The agency's items (wire stories, photos) that were used, each with its totals over every use found for it, whenever it was found: detections, distinct publishers, first and last use, best score and the detections per band. Items never used are not known and are not listed. Give content_type and either published_from and published_to (the items published on the wire in the period, ranked by sort) or source_id (the item with that agency id, one per subscription holding it, in one page with no cursor), else 400. The period selects items by when they were published, not by when they were used: items are tracked for up to about 30 days after publication, and every use found in that time is counted.
A period may be at most 31 days: 31 calendar days when both ends are dates, otherwise 31 × 24 hours and one more hour. Dates are read in time_zone, else the subscription's own, and a date-only end includes its day. published_from may be earlier than the day records begin, since an item published before the export began can still be used after it. A request reads the key's one subscription, and a request whose period reaches more than 64 shards of storage is 400 ("narrow the period or the subscriptions"). The cursor carries a hash of the request and is refused with 400 if the period, sort or time zone change. Not counted against the daily row allowance.
Authentication: A key or an access token (Authorization: Bearer …) with the scope detections:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
content_type | query | string | yes | text (wire stories) or image (photos), in the key's scope.one of text, image |
published_from | query | string | no | With published_to, required unless source_id is given: the items published on the wire in the period. A date (that day's start in the request's time zone) or an ISO 8601 time with Z or an offset. |
published_to | query | string | no | The period's end, exclusive; a date is the end of that day. A future value is read as now. |
source_id | query | string | no | The agency's own id for its item (a URN, a UUID…), at most 200 characters. Answers every match (normally one), in one page: limit does not apply and there is no cursor.at most 200 characters |
time_zone | query | string | no | An IANA time zone name for date-only bounds. Default: the subscription's own. Echoed as written. |
sort | query | string | no | With published_from and published_to only (400 with source_id): most detections first (the default), most publishers, latest first use, or latest publish time. Ties are broken by internal_id, highest first. -detections and -publishers page on counts that can grow: an item that gains uses between two pages can be skipped (never repeated); the other sorts are stable.one of -detections, -publishers, -first_detected_at, -published_at; default -detections |
limit | query | integer | no | The most items to return, up to 500. 1 to 500; default 100 |
cursor | query | QueryCursor | no | The next_cursor of the previous page of the same request. |
subscription_id | query | integer | no | Optional and not repeatable: a key reads exactly its own subscription (/v1/me), which may be named here. Any other id is 400 with the same text whether it exists or not ("subscription 1234 is not available to this key").1 to 999,999,999,999,999 |
schema_version | query | string | no | The detection schema version. v1, the default, is the only one.one of v1; default v1 |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | A page of items. | application/json: SourcesPage | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (SourcesPage)
| Field | Type | Nullable | Description |
|---|---|---|---|
data | array of Source | no | The items, in the selector's order. |
data[].content_type | string | no | one of text, image |
data[].internal_id | integer | no | EzyInsights' id for the item (source.internal_id on its detections). |
data[].subscription_id | integer | no | The subscription these totals are for. |
data[].source_id | string or null | yes | The agency's own id for the item (a URN, a UUID…), from its newest detection. |
data[].published_at | string (date-time) or null | yes | When the agency published the item, from its newest detection. |
data[].headline optional | string or null | yes | Text only. The wire story's own headline, from its newest detection (source.headline); null until a detection carries it.at most 1,000 characters |
data[].image_url optional | string or null | yes | Images only. Our signed proxy address of the agency's photo, as on its detections. |
data[].detections | integer | no | How many detections the item has. |
data[].publishers | integer | no | How many distinct publishers used it (publisher ids, or domains for detections without one). |
data[].first_detected_at | string (date-time) | no | Its first use, the earliest first_detected_at of its detections. |
data[].last_detected_at | string (date-time) | no | The latest first_detected_at of its detections. |
data[].best_score | integer | no | The highest score of its detections, rounded. |
data[].bands | object | no | The detections per band, strongest first; the content type's bands only (text max … off, image high … low). |
data[].bands.max optional | integer | no | |
data[].bands.high optional | integer | no | |
data[].bands.medium optional | integer | no | |
data[].bands.low optional | integer | no | |
data[].bands.off optional | integer | no | |
next_cursor | QueryCursor or any or null | yes | The next page's cursor, or null. |
has_more | boolean | no | True when there may be another page (which can be empty). |
from optional | string (date-time) | no | With a period selector, the period's start as resolved, inclusive. |
to optional | string (date-time) | no | With a period selector, the period's end as resolved, exclusive. |
time_zone optional | string | no | With a period selector, the time zone it was read in. |
as_of | string (date-time) or null | yes | As on the change stream. |
GET /v1/sources/{content_type}/{internal_id}
One used item with its totals
The item, as /v1/sources gives it, with as_of, for the key's subscription. An item that is unknown, never used, or outside the key's scope is 404. Not counted against the daily row allowance.
Authentication: A key or an access token (Authorization: Bearer …) with the scope detections:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
content_type | path | string | yes | text or image; anything else is 404.one of text, image |
internal_id | path | integer | yes | The item's internal_id (source.internal_id on its detections); anything but a positive integer is 404.at least 1 |
subscription_id | query | integer | no | Optional and not repeatable: a key reads exactly its own subscription (/v1/me), which may be named here. Any other id is 400 with the same text whether it exists or not ("subscription 1234 is not available to this key").1 to 999,999,999,999,999 |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The item. | application/json: SourceAnswer | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: there is no endpoint at this path (a trailing slash never matches), or nothing with this id in the key's scope: no such detection, or no used item at /v1/sources/{content_type}/{internal_id} (an item that is unknown, never used or another subscription's reads the same). The rate-limit headers are sent only with the second, when the credential was verified. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (SourceAnswer)
| Field | Type | Nullable | Description |
|---|---|---|---|
content_type | string | no | one of text, image |
internal_id | integer | no | EzyInsights' id for the item (source.internal_id on its detections). |
subscription_id | integer | no | The subscription these totals are for. |
source_id | string or null | yes | The agency's own id for the item (a URN, a UUID…), from its newest detection. |
published_at | string (date-time) or null | yes | When the agency published the item, from its newest detection. |
headline optional | string or null | yes | Text only. The wire story's own headline, from its newest detection (source.headline); null until a detection carries it.at most 1,000 characters |
image_url optional | string or null | yes | Images only. Our signed proxy address of the agency's photo, as on its detections. |
detections | integer | no | How many detections the item has. |
publishers | integer | no | How many distinct publishers used it (publisher ids, or domains for detections without one). |
first_detected_at | string (date-time) | no | Its first use, the earliest first_detected_at of its detections. |
last_detected_at | string (date-time) | no | The latest first_detected_at of its detections. |
best_score | integer | no | The highest score of its detections, rounded. |
bands | Source/properties/bands | no | The detections per band, strongest first; the content type's bands only (text max … off, image high … low). |
bands.max optional | integer | no | |
bands.high optional | integer | no | |
bands.medium optional | integer | no | |
bands.low optional | integer | no | |
bands.off optional | integer | no | |
as_of | string (date-time) or null | yes | As on the change stream. |
GET /v1/sources/{content_type}/{internal_id}/detections
Every use of one item
The current state of every detection of the item, as a detections collection, without event. The item is found as GET /v1/sources/{content_type}/{internal_id} finds it, in the key's subscription. Every shared filter except source_id; content_type, if given, must be the path's. Sorts: newest first (the default), strongest first, or publisher: grouped by publisher id, detections without a publisher first (by domain), newest first within a publisher; a grouping, not an alphabetical order. The cursor carries a hash of the item, the filters, the sort and fields. The rows returned count against the daily row allowance.
Authentication: A key or an access token (Authorization: Bearer …) with the scope detections:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
content_type | path | string | yes | text or image; anything else is 404.one of text, image |
internal_id | path | integer | yes | The item's internal_id (source.internal_id on its detections); anything but a positive integer is 404.at least 1 |
sort | query | string | no | Newest first, by score (highest first), or grouped by publisher id; ties by id.one of -first_detected_at, -score, publisher; default -first_detected_at |
limit | query | integer | no | The most rows to return, up to 1,000. 1 to 1,000; default 100 |
cursor | query | QueryCursor | no | The next_cursor of the previous page of the same request. |
subscription_id | query | integer | no | Optional and not repeatable: a key reads exactly its own subscription (/v1/me), which may be named here. Any other id is 400 with the same text whether it exists or not ("subscription 1234 is not available to this key").1 to 999,999,999,999,999 |
content_type | query | string | no | Only this content type. It must be one the key can read; unset means every type in its scope. one of text, image |
publisher_id | query | array of integer | no | Only detections in articles of these publishers (article.publisher.id). Repeatable or comma-separated; at most 50 values. A detection without a publisher never matches.at most 50 values; each 1 to 999,999,999,999,999 |
exclude_publisher_id | query | array of integer | no | Every publisher except these. Repeatable or comma-separated; at most 50 values. A detection without a publisher is kept. at most 50 values; each 1 to 999,999,999,999,999 |
domain | query | array of string | no | Only detections in articles on these domains (article.domain). Repeatable or comma-separated; at most 20 values. Each is a domain (example-daily.test) or an http(s) URL with no path; it is compared in lower case and punycode, so münchen.example and xn--mnchen-3ya.example are the same. A path, port, query, fragment or user name is 400.at most 20 values |
exclude_domain | query | array of string | no | Every domain except these, written as for domain. Repeatable or comma-separated; at most 20 values. A detection without a domain is kept.at most 20 values |
min_band | query | string | no | Only detections at this band or stronger. Text bands run off < low < medium < high < max; image bands low < medium < high, and the same word means the same step for both types. So min_band=off keeps everything, min_band=low drops text off, and min_band=max keeps only text max and excludes every image.one of off, low, medium, high, max |
band | query | array of string | no | Exactly these bands (band=medium&band=high or band=medium,high). Repeatable or comma-separated. off and max match no image.each one of off, low, medium, high, max |
min_score | query | integer | no | Only detections whose strength.score, rounded to a whole number, is at least this: the usage percentage for text (0–100), the match score for images (0–99).0 to 100 |
print | query | boolean | no | true for print articles only, false for everything else. Image detections are never print. |
article_id | query | integer | no | Only detections in this publisher article (article.id).1 to 999,999,999,999,999 |
fields | query | string | no | Return only these fields: a comma-separated list of paths from the detection schema (fields=first_detected_at,strength,article.url,article.publisher). A path is a field (article.url) or an object holding some (strength, article.publisher), returned whole. id and version are always returned; the fields keep the detection's order; a field the detection's content type does not have stays absent. An unknown path is 400. |
schema_version | query | string | no | The detection schema version. v1, the default, is the only one.one of v1; default v1 |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | A page of the item's uses. | application/json: SourceDetectionsPage | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: there is no endpoint at this path (a trailing slash never matches), or nothing with this id in the key's scope: no such detection, or no used item at /v1/sources/{content_type}/{internal_id} (an item that is unknown, never used or another subscription's reads the same). The rate-limit headers are sent only with the second, when the credential was verified. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited as on every authenticated endpoint (the rate-limit headers only when the credential was verified), or daily_allowance: the key or its subscription has used its daily row allowance. The detail gives the reset (the next 00:00 UTC) and Retry-After the seconds until then. The cursor you hold stays valid. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (SourceDetectionsPage)
| Field | Type | Nullable | Description |
|---|---|---|---|
data | array of Detection | no | The item's detections' current states, in the requested sort, without event. |
next_cursor | QueryCursor or any or null | yes | The next page's cursor, or null. |
has_more | boolean | no | True when the page is full (the next can be empty). |
as_of | string (date-time) or null | yes | As on the change stream. |
GET /v1/reports/usage
Counts of uses, by time and by publisher, band or type
Counts of detections, distinct publishers (publishers) and items used for the first time (new_sources) in a period, one group per time bucket and per value of the other groups. Buckets are the time zone's days, ISO weeks (Monday start) or months, or whole hours; without a time grain, the whole period is one group. Zones whose offset is not a whole hour (India, Nepal, Adelaide) are counted to the nearest hour, and the answer says approximate_days: true.
new_sources counts items used for the first time in the bucket, at any publisher; grouped by publisher, items used for the first time at that publisher, so the publisher groups add up to more than totals.new_sources, which counts each item once. new_sources with a publisher_id filter is refused unless grouped by publisher. publishers is exact within one content type and UTC year; across several it is summed and publishers_summed: true says so (group by content_type for exact counts). There is no subscription grouping: a key has one subscription (400 "subscription is not a grouping: a key has one").
Periods: at most 7 days grouped by publisher and hour; at most 92 days by publisher and day or week; at most 366 days otherwise. A request whose groups exceed 10,000 in one subscription, content type and year is 400 ("narrow the period or the grouping"). from may not be earlier than the day records begin. Groups are ordered by the time bucket, then detections descending, then the other keys. The cursor is an offset with the request's hash: a page may shift if data arrives between pages. country and customer groups come later (400 "not available yet" until then). Not counted against the daily row allowance.
Authentication: A key or an access token (Authorization: Bearer …) with the scope reports:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string | yes | The period's start, inclusive: a date (that day's start in the time zone) or an ISO 8601 time. |
to | query | string | yes | The period's end, exclusive; a date is the end of that day. A future value is read as now. |
time_zone | query | string | no | The IANA time zone days, weeks and months are counted in. Default: the subscription's own. |
group_by | query | array of string | no | Repeatable, or a comma-separated list: at most 2 groups, at most one of hour, day, week and month.at most 2 values; each one of hour, day, week, month, publisher, band, content_type |
metrics | query | array of string | no | Repeatable, or a comma-separated list. detections is always included.each one of detections, publishers, new_sources |
subscription_id | query | integer | no | Optional and not repeatable: a key reads exactly its own subscription (/v1/me), which may be named here. Any other id is 400 with the same text whether it exists or not ("subscription 1234 is not available to this key").1 to 999,999,999,999,999 |
content_type | query | string | no | Only this content type. It must be one the key can read; unset means every type in its scope. one of text, image |
min_band | query | string | no | Only detections at this band or stronger. Text bands run off < low < medium < high < max; image bands low < medium < high, and the same word means the same step for both types. So min_band=off keeps everything, min_band=low drops text off, and min_band=max keeps only text max and excludes every image.one of off, low, medium, high, max |
band | query | array of string | no | Exactly these bands (band=medium&band=high or band=medium,high). Repeatable or comma-separated. off and max match no image.each one of off, low, medium, high, max |
publisher_id | query | array of integer | no | Only detections in articles of these publishers (article.publisher.id). Repeatable or comma-separated; at most 50 values. A detection without a publisher never matches.at most 50 values; each 1 to 999,999,999,999,999 |
limit | query | integer | no | Groups per page, up to 10,000. 1 to 10,000; default 1000 |
cursor | query | QueryCursor | no | The next_cursor of the previous page: an offset with the request's hash, refused if the request changed. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | A page of groups, with the period's totals. | application/json: UsageReport | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (UsageReport)
| Field | Type | Nullable | Description |
|---|---|---|---|
from | string (date-time) | no | The period's start as resolved, inclusive. |
to | string (date-time) | no | The period's end as resolved, exclusive (now, if to was in the future). |
time_zone | string | no | The time zone buckets are counted in. |
group_by | array of string | no | each one of hour, day, week, month, publisher, band, content_type |
metrics | array of string | no | each one of detections, publishers, new_sources |
data | array of UsageGroup | no | This page's groups. |
data[].hour optional | string | no | The bucket's local start, YYYY-MM-DDTHH. |
data[].day optional | string | no | The local day, YYYY-MM-DD. |
data[].week optional | string | no | The ISO week, YYYY-Www (Monday start, in the time zone). |
data[].month optional | string | no | The local month, YYYY-MM. |
data[].publisher optional | object or null | yes | The publisher, or null for detections without a publisher id (then domain). |
data[].publisher.id optional | integer | yes | |
data[].publisher.name optional | string or null | yes | |
data[].domain optional | string or null | yes | With publisher null, the detections' domain (null when unknown). |
data[].band optional | string | no | one of off, low, medium, high, max |
data[].content_type optional | string | no | one of text, image |
data[].detections | integer | no | |
data[].publishers optional | integer | no | Distinct publishers; see publishers_summed. |
data[].new_sources optional | integer | no | Items used for the first time; at that publisher when grouped by publisher. |
totals | object | no | The whole period, with the metrics asked for; new_sources counts each item once. |
totals.detections | integer | no | |
totals.publishers optional | integer | no | |
totals.new_sources optional | integer | no | |
next_cursor | QueryCursor or any or null | yes | The next page's cursor, or null. |
has_more | boolean | no | |
as_of | string (date-time) or null | yes | As on the change stream. |
approximate_days | boolean | no | True when a bucket boundary was moved to the nearest whole hour. |
publishers_summed | boolean | no | True when a publishers count in the answer is a sum over several content types or UTC years, so a publisher can be counted more than once. |
GET /v1/subscriptions/{id}/sites
A subscription's sites
The subscription's list of sites, A to Z by host then path: each with its customer and priority, the EzyInsights publishers it matches, its tracking status, its collection health and its last action. The whole list is read at once (at most 10,000 sites) and the filters are applied to it; count is how many sites match them, across every page. The answer carries the list's ETag, which a write may send back as If-Match. A subscription outside the key's scope, or one that does not exist, is 404.
Authentication: A key or an access token (Authorization: Bearer …) with the scope detections:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | The key's subscription (/v1/me names it). Any other id is 404, whether it exists or not.at least 1 |
q | query | string | no | The start of a host (bild finds bild.de), normalised as a host is: lower case, punycode, www. stripped. A value with a path is 400. |
customer | query | string | no | Only customers (true) or only the others (false).one of true, false |
priority | query | string | no | One priority. one of high, normal, low |
match | query | string | no | How the site matches EzyInsights publishers: matched (one), several (more than one), unmatched (none).one of matched, several, unmatched |
health | query | string | no | The site's collection health (the worst of its publishers'). A site without one (unmatched, or not measured yet) matches no value. one of healthy, degraded, not_collecting, unknown |
tracking_status | query | string | no | One tracking status. one of tracked, requested, being_added, cannot_track |
problems | query | string | no | Only the sites that need attention (true) or only the others (false). A site is a problem when its collection is degraded or not_collecting, its request is cannot_track or still requested, it matches no publisher, or it matches several and no path narrows it. being_added and unknown are not problems.one of true, false |
group | query | string | no | One group, matched without regard to case (acm finds ACM), its spaces trimmed and collapsed as a stored group's are; 1 to 80 characters.at most 80 characters |
limit | query | integer | no | Sites per page, 1 to 1,000. 1 to 1,000; default 100 |
cursor | query | string | no | The next_cursor of the previous page. It carries the filters: a cursor sent with other filters (or another subscription) is 400; limit may change. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | One page of the list. | application/json: SitesPage | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: the subscription is not one of the key's, or does not exist, or the site is not on its list. The answer is the same in every case. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (SitesPage)
| Field | Type | Nullable | Description |
|---|---|---|---|
data | array of Site | no | The page, A to Z by host then path. |
data[].id | string | no | The site's id; address it as …/sites/{id}.pattern ^site_[0-9A-Z]{26}$ |
data[].subscription_id | integer | no | The subscription whose list it is on. |
data[].host | string | no | The identity of the site with path: a registrable domain or a host under it, lower case, in punycode, without www.. |
data[].display | string | no | The host in Unicode, for display (münchen.de for xn--mnchen-3ya.de). |
data[].domain | string | no | The registrable domain of host, by the public suffix list the exporters use, as detections' article.domain has it. |
data[].path | string | no | A path prefix that narrows the site; / for the whole host. |
data[].name | string or null | yes | The name given in a list or by a change; null when none was. |
data[].customer | boolean | no | The agency licenses this site. |
data[].priority | string | no | The agency's own ranking. one of high, normal, low |
data[].publishers | array of object | no | The EzyInsights publishers the site matches, by id (all of them when it matches several). |
data[].publishers[].id | integer | no | The publisher id, as detections' article.publisher.id has it. |
data[].publishers[].name | string or null | yes | The publisher's name. |
data[].publishers[].retired | boolean | no | The publisher is no longer collected; its old detections still match. |
data[].match | string | no | matched: one publisher; several: more than one; unmatched: none.one of matched, several, unmatched |
data[].tracking | object | no | Whether EzyInsights collects the site. A new site without a matching publisher is requested; only EzyInsights staff move a request. |
data[].tracking.status | string | no | The tracking status. one of tracked, requested, being_added, cannot_track |
data[].tracking.since | string (date-time) | no | When the status last changed. |
data[].tracking.reason | string or null | yes | Why it cannot be tracked; null otherwise. one of paywall, blocks_collection, not_news, duplicate, other |
data[].tracking.reason_text | string or null | yes | More about the reason, for this subscription; null when none. |
data[].health | object or null | yes | How well it is collected: the worst of its publishers'. Null when it matches no publisher or none has been measured yet. |
data[].health.status | string | yes | The collection status. one of healthy, degraded, not_collecting, unknown |
data[].health.since | string (date-time) | yes | When the status began. |
data[].health.last_24h | integer or null | yes | Articles collected in the last 24 hours. |
data[].health.usual_day | integer or null | yes | Articles collected on a usual day. |
data[].last_action | object or null | yes | The newest action on the site or its publishers that this subscription may see. |
data[].last_action.at | string (date-time) | yes | When. |
data[].last_action.by_name | string | yes | Who (a person's name, a key's name, or EzyInsights). |
data[].last_action.kind | string | yes | What kind of action. one of note, tracking, health, import |
data[].last_action.text | string | yes | What was done. |
data[].source | object | no | How the site was added. |
data[].source.kind | string | no | upload (a file), api (this API), app (the EzyInsights app), back_office (EzyInsights' earlier customer list).one of upload, api, app, back_office |
data[].source.file | string or null | yes | The file's name for an upload; else null. |
data[].added_at | string (date-time) | no | When it was added. |
data[].added_by_name | string | no | Who added it. |
data[].updated_at | string (date-time) | no | When it last changed. |
data[].updated_by_name | string | no | Who changed it last. |
data[].version | integer | no | The site's own change counter, for information; If-Match takes the list's ETag. |
data[].group | string or null | yes | The agency's own group for the site, as given; null when it has none. |
data[].pinned | boolean | no | true when the site's publishers are the ids its list gave (publisher_ids), not the ones its address matches; such a site is never re-matched. |
data[].publisher_ids | array of integer | no | The publisher ids the site is pinned to; empty when it is matched by its address. |
data[].labels | object | no | Up to 5 columns kept from the agency's list, key to value. |
next_cursor | string or null | yes | Send as cursor for the next page; null on the last. |
has_more | boolean | no | Whether another page follows. |
count | integer | no | The sites that match the filters, on every page. |
collection_incident | object or null | yes | An open incident in EzyInsights' collection as a whole (fewer articles than usual everywhere), during which site health is not judged; null when there is none. |
collection_incident.since | string (date-time) | yes | The hour it began. |
collection_incident.stories | integer | yes | Articles collected in its last hour. |
collection_incident.expected | integer | yes | Articles expected in an hour. |
health_checked_at | string (date-time) or null | yes | When site health was last measured; null before the first time. |
PATCH /v1/subscriptions/{id}/sites
Change several sites at once
Sets customer, priority, group or several of them on up to 1,000 sites of the list, by id (group: null removes the group). Ids that are not on this subscription's list are reported in missing and never applied; sites that already have the values are unchanged, and a call that changes nothing writes nothing. If-Match is optional (see Sites).
Authentication: A key or an access token (Authorization: Bearer …) with the scope sites:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | The key's subscription (/v1/me names it). Any other id is 404, whether it exists or not.at least 1 |
If-Match | header | string | no | The list's ETag as the call last saw it ("7"). Optional: when it no longer matches, the call writes nothing and answers 412. Without it, the call is still guarded by the version it reads, and retries once if the list changes in between. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional, as without the header. |
Request body
As application/json:
| Field | Type | Required | Description |
|---|---|---|---|
ids | array of string | yes | 1 to 1,000 distinct site ids. at most 1,000 values |
customer | boolean | no | The new customer for every site. |
priority | string | no | The new priority for every site. one of high, normal, low |
group | string or null | no | The new group for every site, its spaces trimmed and collapsed, in the spelling the list already uses for it when there is one (matched without regard to case); null or empty removes it. at most 80 characters |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | What changed; the ETag is the list's after the call. | application/json: SitesPatchResult | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: the subscription is not one of the key's, or does not exist, or the site is not on its list. The answer is the same in every case. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 412 | precondition_failed: the list changed since the If-Match version (or, without If-Match, twice while the call ran); nothing was written. The ETag is the list's version now: read the list again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 413 | content_too_large: the body is larger than 5 MB (5,000,000 bytes), or an import has more than 20,000 rows. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (SitesPatchResult)
| Field | Type | Nullable | Description |
|---|---|---|---|
changed | integer | no | Sites changed. |
unchanged | integer | no | Sites that already had the values. |
missing | array of string | no | Ids not on this subscription's list; nothing was applied to them. |
POST /v1/subscriptions/{id}/sites/import
Import a sites list or a customer list
Adds sites, or replaces the list, from rows. list: sites with add adds the sites not listed yet; with replace it also removes the sites not in the rows (their history is kept). list: customer with add adds the missing sites and marks every site in the rows as a customer; with replace it also clears customer on the sites not in the rows, and keeps them. add sets a priority only on new sites and on rows that give one.
Send dry_run: true first: the answer is the preview (what would be added, changed, removed, the rows skipped with their reasons, the rows that overlap a listed site) and the list version it was made from. Then send the same rows without dry_run, with that version as If-Match: "<version>"; if the list changed meanwhile the answer is 412. Without If-Match the call reads the list's version itself and retries once if the list moves in between. Rows that overlap a listed site are kept only with confirm_overlaps: true (else 409 state_conflict). A row's site is a host or a URL: a URL is reduced to its registrable domain unless keep_host is true (then its host is kept); its path is dropped, and path narrows the site instead. A bare host is kept as given. A query or a fragment is cut off, and a path's last segment that names a page rather than a section (it holds a ., or is contact, about, index, home, privacy, terms and the like) is dropped, keeping the rest of the path (/wires/aap/index.html becomes /wires/aap); the preview lists the rows it happened to. Invalid rows are skipped and listed (the first 100), never fatal.
A row may carry the agency's group (a group already in use is matched without regard to case and keeps its spelling; an upload never removes a group), up to 5 labels, and publisher_ids: EzyInsights publisher ids that pin the site to those publishers instead of matching its address (unknown ids are dropped and listed; a row whose ids are all unknown is matched by its address; a file may name at most 10,000 different ids). add sets a group and labels only where the row gives them. replace sets pins on every row only when some row gives publisher_ids (a row without a known id is then matched by its address again, unless that address would match more than 200 publishers), and labels on every row only when some row gives labels; a file without the field keeps what is stored.
The rows may also be sent as text/csv (UTF-8), with list, mode and the other options as query parameters: a first line whose first cell is site, domain, url or host is a header, and then the columns path, name, priority, keep_host, group, publisher_ids (ids separated by commas, semicolons or spaces) and label:<key> (one label each) are read by name; without a header the first column is the site. The delimiter is ,, ; or a tab. With application/json the query parameters are refused.
At most 20,000 rows and 5 MB (413); a list may hold 10,000 sites, counted after reduction and de-duplication (409 limit_reached, naming the count over). Idempotency-Key is accepted but not stored in this version: an add retried with the same If-Match is refused 412, which is the protection. A change applies to detections found or re-scored after it; detections already delivered are not re-sent.
Authentication: A key or an access token (Authorization: Bearer …) with the scope sites:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | The key's subscription (/v1/me names it). Any other id is 404, whether it exists or not.at least 1 |
If-Match | header | string | no | The list's ETag as the call last saw it ("7"). Optional: when it no longer matches, the call writes nothing and answers 412. Without it, the call is still guarded by the version it reads, and retries once if the list changes in between. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional, as without the header. |
Idempotency-Key | header | string | no | Accepted and not stored in this version (see above). |
list | query | string | no | text/csv only, and then required: sites or customer.one of sites, customer |
mode | query | string | no | text/csv only, and then required: add or replace.one of add, replace |
default_priority | query | string | no | text/csv only: the priority of new sites whose row gives none.one of high, normal, low; default normal |
dry_run | query | string | no | text/csv only: true answers the preview and writes nothing.one of true, false |
confirm_overlaps | query | string | no | text/csv only: true keeps rows that overlap a listed site.one of true, false |
Request body
As application/json:
| Field | Type | Required | Description |
|---|---|---|---|
list | string | yes | A sites list, or a customer list (its sites are marked as customers). one of sites, customer |
mode | string | yes | add, or replace (also removes, or un-marks, what is not in the rows).one of add, replace |
default_priority | string | no | The priority of new sites whose row gives none. one of high, normal, low; default normal |
rows | array of object | yes | The sites, at most 20,000. at most 20,000 values |
dry_run | boolean | no | true: answer the preview and write nothing. |
confirm_overlaps | boolean | no | true: keep rows that overlap a listed site. |
As text/csv:
| Field | Type | Required | Description |
|---|
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | With dry_run: the preview, and the version to send as If-Match. Without: what was applied, and the list's version after it (also the ETag). | application/json: SitesPreview or SitesImportResult | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: the subscription is not one of the key's, or does not exist, or the site is not on its list. The answer is the same in every case. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the list would hold more than 10,000 sites (the detail names how many over), or the change is too large for one request. state_conflict: rows overlap listed sites without confirm_overlaps, or the host and path are another site's. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the list changed since the If-Match version (or, without If-Match, twice while the call ran); nothing was written. The ETag is the list's version now: read the list again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 413 | content_too_large: the body is larger than 5 MB (5,000,000 bytes), or an import has more than 20,000 rows. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body
| Field | Type | Nullable | Description |
|---|
GET /v1/subscriptions/{id}/sites/{site}
One site
The site, with its publishers, its health and its newest 20 actions (tracking changes, health changes, notes and imports that this subscription may see). The ETag is the list's. A site not on this subscription's list is 404.
Authentication: A key or an access token (Authorization: Bearer …) with the scope detections:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | The key's subscription (/v1/me names it). Any other id is 404, whether it exists or not.at least 1 |
site | path | string | yes | A site id (site_…), or the site's host[/path] URL-encoded as one path segment (shared.test%2Fde-de%2Fnachrichten). A value that is neither is 400. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The site. | application/json: SiteWithActions | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: the subscription is not one of the key's, or does not exist, or the site is not on its list. The answer is the same in every case. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (SiteWithActions)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The site's id; address it as …/sites/{id}.pattern ^site_[0-9A-Z]{26}$ |
subscription_id | integer | no | The subscription whose list it is on. |
host | string | no | The identity of the site with path: a registrable domain or a host under it, lower case, in punycode, without www.. |
display | string | no | The host in Unicode, for display (münchen.de for xn--mnchen-3ya.de). |
domain | string | no | The registrable domain of host, by the public suffix list the exporters use, as detections' article.domain has it. |
path | string | no | A path prefix that narrows the site; / for the whole host. |
name | string or null | yes | The name given in a list or by a change; null when none was. |
customer | boolean | no | The agency licenses this site. |
priority | string | no | The agency's own ranking. one of high, normal, low |
publishers | array of object | no | The EzyInsights publishers the site matches, by id (all of them when it matches several). |
publishers[].id | integer | no | The publisher id, as detections' article.publisher.id has it. |
publishers[].name | string or null | yes | The publisher's name. |
publishers[].retired | boolean | no | The publisher is no longer collected; its old detections still match. |
match | string | no | matched: one publisher; several: more than one; unmatched: none.one of matched, several, unmatched |
tracking | object | no | Whether EzyInsights collects the site. A new site without a matching publisher is requested; only EzyInsights staff move a request. |
tracking.status | string | no | The tracking status. one of tracked, requested, being_added, cannot_track |
tracking.since | string (date-time) | no | When the status last changed. |
tracking.reason | string or null | yes | Why it cannot be tracked; null otherwise. one of paywall, blocks_collection, not_news, duplicate, other |
tracking.reason_text | string or null | yes | More about the reason, for this subscription; null when none. |
health | object or null | yes | How well it is collected: the worst of its publishers'. Null when it matches no publisher or none has been measured yet. |
health.status | string | yes | The collection status. one of healthy, degraded, not_collecting, unknown |
health.since | string (date-time) | yes | When the status began. |
health.last_24h | integer or null | yes | Articles collected in the last 24 hours. |
health.usual_day | integer or null | yes | Articles collected on a usual day. |
last_action | object or null | yes | The newest action on the site or its publishers that this subscription may see. |
last_action.at | string (date-time) | yes | When. |
last_action.by_name | string | yes | Who (a person's name, a key's name, or EzyInsights). |
last_action.kind | string | yes | What kind of action. one of note, tracking, health, import |
last_action.text | string | yes | What was done. |
source | object | no | How the site was added. |
source.kind | string | no | upload (a file), api (this API), app (the EzyInsights app), back_office (EzyInsights' earlier customer list).one of upload, api, app, back_office |
source.file | string or null | yes | The file's name for an upload; else null. |
added_at | string (date-time) | no | When it was added. |
added_by_name | string | no | Who added it. |
updated_at | string (date-time) | no | When it last changed. |
updated_by_name | string | no | Who changed it last. |
version | integer | no | The site's own change counter, for information; If-Match takes the list's ETag. |
group | string or null | yes | The agency's own group for the site, as given; null when it has none. |
pinned | boolean | no | true when the site's publishers are the ids its list gave (publisher_ids), not the ones its address matches; such a site is never re-matched. |
publisher_ids | array of integer | no | The publisher ids the site is pinned to; empty when it is matched by its address. |
labels | object | no | Up to 5 columns kept from the agency's list, key to value. |
actions | array of object | no | The newest 20 actions on the site and its publishers that this subscription may see, newest first. |
actions[].id | string | no | The action's id. |
actions[].at | string (date-time) | no | When. |
actions[].by_name | string | no | Who. |
actions[].kind | string | no | What kind of action. one of note, tracking, health, import |
actions[].text | string | no | What was done. |
actions[].visibility | string | no | subscription: seen by this subscription; everyone: seen by every subscription that lists the publisher.one of subscription, everyone |
actions[].publisher_id | integer or null | yes | The publisher it is about; null when it is about the site. |
PUT /v1/subscriptions/{id}/sites/{site}
Create or change one site
By id: changes the site. By host and path: changes the site when it is listed, else creates it (customer false unless given, priority normal unless given; a site that matches no EzyInsights publisher is requested for tracking). A new site that overlaps a listed one (example.de/sport beside example.de) is 409 state_conflict; add it with an import and confirm_overlaps. A call that changes nothing writes nothing and answers 200. A new host or path of a pinned site changes its address only and keeps the pin. A site is found by its address as given; when a call creates one, a path's last segment that names a page (index.html, contact) is dropped. If-Match is optional (see Sites).
Authentication: A key or an access token (Authorization: Bearer …) with the scope sites:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | The key's subscription (/v1/me names it). Any other id is 404, whether it exists or not.at least 1 |
site | path | string | yes | A site id (site_…), or the site's host[/path] URL-encoded as one path segment (shared.test%2Fde-de%2Fnachrichten). A value that is neither is 400. |
If-Match | header | string | no | The list's ETag as the call last saw it ("7"). Optional: when it no longer matches, the call writes nothing and answers 412. Without it, the call is still guarded by the version it reads, and retries once if the list changes in between. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional, as without the header. |
Request body
As application/json:
| Field | Type | Required | Description |
|---|---|---|---|
customer | boolean | no | The agency licenses the site. On a create, false unless given. |
priority | string | no | The site's priority. On a create, normal unless given. one of high, normal, low |
name | string or null | no | A name for the site; null or empty removes it. at most 200 characters |
group | string or null | no | The agency's group for the site; null or empty removes it. at most 80 characters |
labels | object | no | The site's labels, replacing its own; keys up to 40 characters. |
publisher_ids | array of integer | no | Pins the site to these EzyInsights publishers instead of its address, also when the call creates it; unknown ids are dropped, and none known is 400. Not with pinned.at most 200 values; each at least 1 |
pinned | boolean | no | false matches a pinned site by its address again, at once. Not with publisher_ids.always false |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | Changed, or already so. | application/json: Site | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 201 | Created. | application/json: Site | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: the subscription is not one of the key's, or does not exist, or the site is not on its list. The answer is the same in every case. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the list would hold more than 10,000 sites (the detail names how many over), or the change is too large for one request. state_conflict: rows overlap listed sites without confirm_overlaps, or the host and path are another site's. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the list changed since the If-Match version (or, without If-Match, twice while the call ran); nothing was written. The ETag is the list's version now: read the list again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 413 | content_too_large: the body is larger than 5 MB (5,000,000 bytes), or an import has more than 20,000 rows. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Site)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The site's id; address it as …/sites/{id}.pattern ^site_[0-9A-Z]{26}$ |
subscription_id | integer | no | The subscription whose list it is on. |
host | string | no | The identity of the site with path: a registrable domain or a host under it, lower case, in punycode, without www.. |
display | string | no | The host in Unicode, for display (münchen.de for xn--mnchen-3ya.de). |
domain | string | no | The registrable domain of host, by the public suffix list the exporters use, as detections' article.domain has it. |
path | string | no | A path prefix that narrows the site; / for the whole host. |
name | string or null | yes | The name given in a list or by a change; null when none was. |
customer | boolean | no | The agency licenses this site. |
priority | string | no | The agency's own ranking. one of high, normal, low |
publishers | array of object | no | The EzyInsights publishers the site matches, by id (all of them when it matches several). |
publishers[].id | integer | no | The publisher id, as detections' article.publisher.id has it. |
publishers[].name | string or null | yes | The publisher's name. |
publishers[].retired | boolean | no | The publisher is no longer collected; its old detections still match. |
match | string | no | matched: one publisher; several: more than one; unmatched: none.one of matched, several, unmatched |
tracking | object | no | Whether EzyInsights collects the site. A new site without a matching publisher is requested; only EzyInsights staff move a request. |
tracking.status | string | no | The tracking status. one of tracked, requested, being_added, cannot_track |
tracking.since | string (date-time) | no | When the status last changed. |
tracking.reason | string or null | yes | Why it cannot be tracked; null otherwise. one of paywall, blocks_collection, not_news, duplicate, other |
tracking.reason_text | string or null | yes | More about the reason, for this subscription; null when none. |
health | object or null | yes | How well it is collected: the worst of its publishers'. Null when it matches no publisher or none has been measured yet. |
health.status | string | yes | The collection status. one of healthy, degraded, not_collecting, unknown |
health.since | string (date-time) | yes | When the status began. |
health.last_24h | integer or null | yes | Articles collected in the last 24 hours. |
health.usual_day | integer or null | yes | Articles collected on a usual day. |
last_action | object or null | yes | The newest action on the site or its publishers that this subscription may see. |
last_action.at | string (date-time) | yes | When. |
last_action.by_name | string | yes | Who (a person's name, a key's name, or EzyInsights). |
last_action.kind | string | yes | What kind of action. one of note, tracking, health, import |
last_action.text | string | yes | What was done. |
source | object | no | How the site was added. |
source.kind | string | no | upload (a file), api (this API), app (the EzyInsights app), back_office (EzyInsights' earlier customer list).one of upload, api, app, back_office |
source.file | string or null | yes | The file's name for an upload; else null. |
added_at | string (date-time) | no | When it was added. |
added_by_name | string | no | Who added it. |
updated_at | string (date-time) | no | When it last changed. |
updated_by_name | string | no | Who changed it last. |
version | integer | no | The site's own change counter, for information; If-Match takes the list's ETag. |
group | string or null | yes | The agency's own group for the site, as given; null when it has none. |
pinned | boolean | no | true when the site's publishers are the ids its list gave (publisher_ids), not the ones its address matches; such a site is never re-matched. |
publisher_ids | array of integer | no | The publisher ids the site is pinned to; empty when it is matched by its address. |
labels | object | no | Up to 5 columns kept from the agency's list, key to value. |
201 body (Site)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The site's id; address it as …/sites/{id}.pattern ^site_[0-9A-Z]{26}$ |
subscription_id | integer | no | The subscription whose list it is on. |
host | string | no | The identity of the site with path: a registrable domain or a host under it, lower case, in punycode, without www.. |
display | string | no | The host in Unicode, for display (münchen.de for xn--mnchen-3ya.de). |
domain | string | no | The registrable domain of host, by the public suffix list the exporters use, as detections' article.domain has it. |
path | string | no | A path prefix that narrows the site; / for the whole host. |
name | string or null | yes | The name given in a list or by a change; null when none was. |
customer | boolean | no | The agency licenses this site. |
priority | string | no | The agency's own ranking. one of high, normal, low |
publishers | array of object | no | The EzyInsights publishers the site matches, by id (all of them when it matches several). |
publishers[].id | integer | no | The publisher id, as detections' article.publisher.id has it. |
publishers[].name | string or null | yes | The publisher's name. |
publishers[].retired | boolean | no | The publisher is no longer collected; its old detections still match. |
match | string | no | matched: one publisher; several: more than one; unmatched: none.one of matched, several, unmatched |
tracking | object | no | Whether EzyInsights collects the site. A new site without a matching publisher is requested; only EzyInsights staff move a request. |
tracking.status | string | no | The tracking status. one of tracked, requested, being_added, cannot_track |
tracking.since | string (date-time) | no | When the status last changed. |
tracking.reason | string or null | yes | Why it cannot be tracked; null otherwise. one of paywall, blocks_collection, not_news, duplicate, other |
tracking.reason_text | string or null | yes | More about the reason, for this subscription; null when none. |
health | object or null | yes | How well it is collected: the worst of its publishers'. Null when it matches no publisher or none has been measured yet. |
health.status | string | yes | The collection status. one of healthy, degraded, not_collecting, unknown |
health.since | string (date-time) | yes | When the status began. |
health.last_24h | integer or null | yes | Articles collected in the last 24 hours. |
health.usual_day | integer or null | yes | Articles collected on a usual day. |
last_action | object or null | yes | The newest action on the site or its publishers that this subscription may see. |
last_action.at | string (date-time) | yes | When. |
last_action.by_name | string | yes | Who (a person's name, a key's name, or EzyInsights). |
last_action.kind | string | yes | What kind of action. one of note, tracking, health, import |
last_action.text | string | yes | What was done. |
source | object | no | How the site was added. |
source.kind | string | no | upload (a file), api (this API), app (the EzyInsights app), back_office (EzyInsights' earlier customer list).one of upload, api, app, back_office |
source.file | string or null | yes | The file's name for an upload; else null. |
added_at | string (date-time) | no | When it was added. |
added_by_name | string | no | Who added it. |
updated_at | string (date-time) | no | When it last changed. |
updated_by_name | string | no | Who changed it last. |
version | integer | no | The site's own change counter, for information; If-Match takes the list's ETag. |
group | string or null | yes | The agency's own group for the site, as given; null when it has none. |
pinned | boolean | no | true when the site's publishers are the ids its list gave (publisher_ids), not the ones its address matches; such a site is never re-matched. |
publisher_ids | array of integer | no | The publisher ids the site is pinned to; empty when it is matched by its address. |
labels | object | no | Up to 5 columns kept from the agency's list, key to value. |
DELETE /v1/subscriptions/{id}/sites/{site}
Remove one site
Removes the site from the list; its history is kept. 204 also when it was not there, and then nothing is written. If-Match is optional (see Sites).
Authentication: A key or an access token (Authorization: Bearer …) with the scope sites:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | The key's subscription (/v1/me names it). Any other id is 404, whether it exists or not.at least 1 |
site | path | string | yes | A site id (site_…), or the site's host[/path] URL-encoded as one path segment (shared.test%2Fde-de%2Fnachrichten). A value that is neither is 400. |
If-Match | header | string | no | The list's ETag as the call last saw it ("7"). Optional: when it no longer matches, the call writes nothing and answers 412. Without it, the call is still guarded by the version it reads, and retries once if the list changes in between. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional, as without the header. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 204 | Removed, or not there. | none | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: the subscription is not one of the key's, or does not exist, or the site is not on its list. The answer is the same in every case. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 412 | precondition_failed: the list changed since the If-Match version (or, without If-Match, twice while the call ran); nothing was written. The ETag is the list's version now: read the list again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
GET /v1/destinations
The subscription’s destinations
The key's subscription's destinations, newest first, at most 10, each with its health: next_run_at and the newest delivery (last_delivery). One page: next_cursor is always null.
Authentication: A key or an access token (Authorization: Bearer …) with the scope destinations:manage.
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The destinations. | application/json: DestinationsPage | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (DestinationsPage)
| Field | Type | Nullable | Description |
|---|---|---|---|
data | array of Destination | no | The destinations, newest first. |
data[].id | string | no | The destination's id (dst_…). |
data[].name | string | no | Its name, 1 to 60 characters. |
data[].provider | string | no | The storage provider. one of s3, s3_compatible, gcs, azure |
data[].bucket | string | no | The bucket (or Azure container). |
data[].prefix | string | no | The key prefix files are written under; empty or ending in /. |
data[].region | string or null | yes | The region, where the provider has one. |
data[].endpoint | string or null | yes | An S3-compatible store's address. |
data[].storage_account | string or null | yes | Azure's storage account. |
data[].auth_mode | string | no | federated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.one of federated, stored |
data[].federation | object or object or object or any or null | yes | A federated destination's values, null until they are sent. |
data[].format | string | no | The file format. one of jsonl, csv, tsv, json, parquet, avro |
data[].compression | string | no | The files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.one of gzip, zstd, none |
data[].format_options | FormatOptions | no | CSV's delimiter, header row and byte order mark; TSV's header row and byte order mark. In a TSV file, a tab or a line break inside a value is replaced by one space. Other formats take none of these. Every format takes evidence_text. |
data[].format_options.delimiter optional | string | no | , or ; for CSV; a tab for TSV.one of ,, ;, |
data[].format_options.header optional | boolean | no | A header row first. default true |
data[].format_options.bom optional | boolean | no | A UTF-8 byte order mark first, for spreadsheets. default false |
data[].format_options.evidence_text optional | boolean | no | Matched sentences, any format: beside each delivery whose rows include text detections, a JSON Lines side file of how each was matched, <name>-evidence-<NNNN>.jsonl.gz (plain .jsonl with compression none), a line each (TextEvidenceAnswer), listed in the manifest's evidence_files with the counts evidence_gone and evidence_unreadable. Only on a destination that carries text; never on a managed legacy feed. Refused otherwise with format_options.evidence_text named.default false |
data[].schema_version | string | no | The detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).one of v1, legacy |
data[].columns | array of string or null | yes | The columns delivered, or null for all: flat column names for CSV and TSV (as /v1/schema/detection lists them), dot paths for JSON Lines and JSON (see Deliveries). |
data[].filter | PushFilter | no | Which detections a destination delivers; every field optional, all given must hold. |
data[].filter.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
data[].filter.min_band optional | string | no | The weakest strength delivered; max means text only reaches it.one of off, low, medium, high, max |
data[].filter.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
data[].filter.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
data[].schedule | object or object or object | no | When a destination delivers. |
data[].next_run_at | string (date-time) or null | yes | The next scheduled delivery; null while none is scheduled (setting up, paused). |
data[].start_at | string (date-time) | no | Where the first delivery started. |
data[].cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
data[].cursor.seq | integer | no | The chunk's sequence number. |
data[].cursor.row | integer | no | Rows of that chunk read. |
data[].delivered_up_to | string (date-time) or null | yes | When the newest done delivery finished; null before the first. |
data[].status | string | no | setting_up until it is first started. It stays active while a delivery retries; failing once a delivery has failed for good (24 hours after its first failure, or at once when the store refuses the credential or the address), and then nothing more is scheduled until it is resumed. disabled is not used for destinations today. See Deliveries.one of setting_up, active, paused, failing, disabled |
data[].last_test_at | string (date-time) or null | yes | The last connection test. |
data[].last_test_ok | boolean or null | yes | Whether it passed. |
data[].last_test_error | string or null | yes | The provider's words when it failed. |
data[].running_since | string (date-time) or null | yes | When the delivery running now started. |
data[].failing_since | string (date-time) or null | yes | When it began failing. |
data[].version | integer | no | Its configuration's version, also the ETag. |
data[].created_at | string (date-time) | no | When it was created. |
data[].created_by_name | string | no | Who created it (a person or a key's name). |
data[].updated_at | string (date-time) | no | Its last change. |
data[].credential | Credential or any or null | yes | The active credential, else the pending one, else null (always null for a federated destination). |
data[].last_delivery | Delivery or any or null | yes | The newest delivery, or null. |
data[].test_prefix | string or null | yes | A managed legacy feed's test prefix, set by EzyInsights staff: its connection test writes the feed's first real hourly file under this prefix instead of prefix, so a credential is proven without touching a live feed; deliveries never use it. Null on any other destination. Read-only with a key. See Managed legacy feeds. |
next_cursor | any or null | yes | Always null (one page). |
has_more | boolean | no | Always false. |
POST /v1/destinations
Create a destination
A destination in setting_up: nothing is delivered until a connection test passes and it is started with …/resume. Stored credentials are added with …/credential; a federated destination's values (from …/setup) with PATCH. A subscription has at most 10 destinations (409 limit_reached), and a start whose first delivery would pass 5,000,000 rows or today's file allowance is refused with the estimate. Send Idempotency-Key so a retried timeout does not create twice (see Destinations and webhooks by code).
Authentication: A key or an access token (Authorization: Bearer …) with the scope destinations:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | no | 1 to 255 visible ASCII characters of your choosing, one per request you mean to make once. A repeat of the same request (method, path and body) with the same key within 24 hours makes nothing new and answers what the first made, as it is now, or 404 if it has since been deleted, with Idempotent-Replayed: true; a secret or a test result is never answered twice. While the first request still runs, a repeat is 409 (retry it in a moment). The same key with another request is 422. A request that was refused, or that has not answered within 5 minutes, leaves the key free. Keys are kept per API key, at most 1,000 in 24 hours: past that, a new key is 429 with Retry-After until the oldest of them is a day old (a repeat, or a request without the header, is still answered).at most 255 characters |
Request body
As application/json:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Its name. at most 60 characters |
provider | string | yes | The storage provider; only those available now are accepted. one of s3, s3_compatible, gcs, azure |
bucket | string | yes | The bucket (or Azure container). |
prefix | string | no | A key prefix, without ..; a trailing / is added.at most 512 characters |
region | string | no | The region; required for S3. |
endpoint | string | no | An S3-compatible store's public https address; only for s3_compatible. |
storage_account | string | no | Azure's storage account; only for azure. |
auth_mode | string | yes | federated (Amazon S3 and Google Cloud Storage) or stored.one of federated, stored |
format | string | yes | The file format; only those available now are accepted. one of jsonl, csv, tsv, json, parquet, avro |
compression | string | yes | The compression: gzip or none for every format; zstd only for Parquet (inside the file), once Parquet files are available.one of gzip, zstd, none |
format_options | FormatOptions | no | CSV's delimiter, header row and byte order mark; TSV's header row and byte order mark. In a TSV file, a tab or a line break inside a value is replaced by one space. Other formats take none of these. Every format takes evidence_text. |
columns | array of string or null | no | The columns to deliver, or none for all: flat column names for CSV and TSV, dot paths for JSON Lines and JSON. An unknown one is refused. |
filter | PushFilter | no | Which detections a destination delivers; every field optional, all given must hold. |
schedule | object or object or object | yes | When a destination delivers. |
start | string | yes | Where the first delivery starts: now, data_start (the start of your data), or a time (ISO 8601 in UTC with Z) at or after the start of your data. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 201 | Created, in setting_up; or, with an Idempotency-Key already used for this request in the last 24 hours, the destination it created, as it is now. | application/json: Destination | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag, Idempotent-Replayed |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 413 | content_too_large: the body is larger than 64 KB (65,536 bytes). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 422 | idempotency_key_reused: this Idempotency-Key was used in the last 24 hours with a different request (another body, path or method). Nothing was done. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 429 | rate_limited: more than 120 requests a minute for this key (Retry-After: 60), more than 10 tests and replays in the last hour for this destination or endpoint (Retry-After: 3600), or, with an Idempotency-Key, 1,000 keys used by this API key in the last 24 hours (Retry-After until the oldest of them is a day old). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
201 body (Destination)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The destination's id (dst_…). |
name | string | no | Its name, 1 to 60 characters. |
provider | string | no | The storage provider. one of s3, s3_compatible, gcs, azure |
bucket | string | no | The bucket (or Azure container). |
prefix | string | no | The key prefix files are written under; empty or ending in /. |
region | string or null | yes | The region, where the provider has one. |
endpoint | string or null | yes | An S3-compatible store's address. |
storage_account | string or null | yes | Azure's storage account. |
auth_mode | string | no | federated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.one of federated, stored |
federation | object or object or object or any or null | yes | A federated destination's values, null until they are sent. |
format | string | no | The file format. one of jsonl, csv, tsv, json, parquet, avro |
compression | string | no | The files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.one of gzip, zstd, none |
format_options | FormatOptions | no | CSV's delimiter, header row and byte order mark; TSV's header row and byte order mark. In a TSV file, a tab or a line break inside a value is replaced by one space. Other formats take none of these. Every format takes evidence_text. |
format_options.delimiter optional | string | no | , or ; for CSV; a tab for TSV.one of ,, ;, |
format_options.header optional | boolean | no | A header row first. default true |
format_options.bom optional | boolean | no | A UTF-8 byte order mark first, for spreadsheets. default false |
format_options.evidence_text optional | boolean | no | Matched sentences, any format: beside each delivery whose rows include text detections, a JSON Lines side file of how each was matched, <name>-evidence-<NNNN>.jsonl.gz (plain .jsonl with compression none), a line each (TextEvidenceAnswer), listed in the manifest's evidence_files with the counts evidence_gone and evidence_unreadable. Only on a destination that carries text; never on a managed legacy feed. Refused otherwise with format_options.evidence_text named.default false |
schema_version | string | no | The detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).one of v1, legacy |
columns | array of string or null | yes | The columns delivered, or null for all: flat column names for CSV and TSV (as /v1/schema/detection lists them), dot paths for JSON Lines and JSON (see Deliveries). |
filter | PushFilter | no | Which detections a destination delivers; every field optional, all given must hold. |
filter.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
filter.min_band optional | string | no | The weakest strength delivered; max means text only reaches it.one of off, low, medium, high, max |
filter.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
filter.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
schedule | object or object or object | no | When a destination delivers. |
next_run_at | string (date-time) or null | yes | The next scheduled delivery; null while none is scheduled (setting up, paused). |
start_at | string (date-time) | no | Where the first delivery started. |
cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
cursor.seq | integer | no | The chunk's sequence number. |
cursor.row | integer | no | Rows of that chunk read. |
delivered_up_to | string (date-time) or null | yes | When the newest done delivery finished; null before the first. |
status | string | no | setting_up until it is first started. It stays active while a delivery retries; failing once a delivery has failed for good (24 hours after its first failure, or at once when the store refuses the credential or the address), and then nothing more is scheduled until it is resumed. disabled is not used for destinations today. See Deliveries.one of setting_up, active, paused, failing, disabled |
last_test_at | string (date-time) or null | yes | The last connection test. |
last_test_ok | boolean or null | yes | Whether it passed. |
last_test_error | string or null | yes | The provider's words when it failed. |
running_since | string (date-time) or null | yes | When the delivery running now started. |
failing_since | string (date-time) or null | yes | When it began failing. |
version | integer | no | Its configuration's version, also the ETag. |
created_at | string (date-time) | no | When it was created. |
created_by_name | string | no | Who created it (a person or a key's name). |
updated_at | string (date-time) | no | Its last change. |
credential | Credential or any or null | yes | The active credential, else the pending one, else null (always null for a federated destination). |
last_delivery | Delivery or any or null | yes | The newest delivery, or null. |
test_prefix | string or null | yes | A managed legacy feed's test prefix, set by EzyInsights staff: its connection test writes the feed's first real hourly file under this prefix instead of prefix, so a credential is proven without touching a live feed; deliveries never use it. Null on any other destination. Read-only with a key. See Managed legacy feeds. |
GET /v1/destinations/{id}
One destination
The destination, its credential (kind, hint and times; never a value) and its newest delivery. The ETag is its version; send it as If-Match to make a change conditional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope destinations:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The destination. | application/json: Destination | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Destination)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The destination's id (dst_…). |
name | string | no | Its name, 1 to 60 characters. |
provider | string | no | The storage provider. one of s3, s3_compatible, gcs, azure |
bucket | string | no | The bucket (or Azure container). |
prefix | string | no | The key prefix files are written under; empty or ending in /. |
region | string or null | yes | The region, where the provider has one. |
endpoint | string or null | yes | An S3-compatible store's address. |
storage_account | string or null | yes | Azure's storage account. |
auth_mode | string | no | federated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.one of federated, stored |
federation | object or object or object or any or null | yes | A federated destination's values, null until they are sent. |
format | string | no | The file format. one of jsonl, csv, tsv, json, parquet, avro |
compression | string | no | The files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.one of gzip, zstd, none |
format_options | FormatOptions | no | CSV's delimiter, header row and byte order mark; TSV's header row and byte order mark. In a TSV file, a tab or a line break inside a value is replaced by one space. Other formats take none of these. Every format takes evidence_text. |
format_options.delimiter optional | string | no | , or ; for CSV; a tab for TSV.one of ,, ;, |
format_options.header optional | boolean | no | A header row first. default true |
format_options.bom optional | boolean | no | A UTF-8 byte order mark first, for spreadsheets. default false |
format_options.evidence_text optional | boolean | no | Matched sentences, any format: beside each delivery whose rows include text detections, a JSON Lines side file of how each was matched, <name>-evidence-<NNNN>.jsonl.gz (plain .jsonl with compression none), a line each (TextEvidenceAnswer), listed in the manifest's evidence_files with the counts evidence_gone and evidence_unreadable. Only on a destination that carries text; never on a managed legacy feed. Refused otherwise with format_options.evidence_text named.default false |
schema_version | string | no | The detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).one of v1, legacy |
columns | array of string or null | yes | The columns delivered, or null for all: flat column names for CSV and TSV (as /v1/schema/detection lists them), dot paths for JSON Lines and JSON (see Deliveries). |
filter | PushFilter | no | Which detections a destination delivers; every field optional, all given must hold. |
filter.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
filter.min_band optional | string | no | The weakest strength delivered; max means text only reaches it.one of off, low, medium, high, max |
filter.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
filter.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
schedule | object or object or object | no | When a destination delivers. |
next_run_at | string (date-time) or null | yes | The next scheduled delivery; null while none is scheduled (setting up, paused). |
start_at | string (date-time) | no | Where the first delivery started. |
cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
cursor.seq | integer | no | The chunk's sequence number. |
cursor.row | integer | no | Rows of that chunk read. |
delivered_up_to | string (date-time) or null | yes | When the newest done delivery finished; null before the first. |
status | string | no | setting_up until it is first started. It stays active while a delivery retries; failing once a delivery has failed for good (24 hours after its first failure, or at once when the store refuses the credential or the address), and then nothing more is scheduled until it is resumed. disabled is not used for destinations today. See Deliveries.one of setting_up, active, paused, failing, disabled |
last_test_at | string (date-time) or null | yes | The last connection test. |
last_test_ok | boolean or null | yes | Whether it passed. |
last_test_error | string or null | yes | The provider's words when it failed. |
running_since | string (date-time) or null | yes | When the delivery running now started. |
failing_since | string (date-time) or null | yes | When it began failing. |
version | integer | no | Its configuration's version, also the ETag. |
created_at | string (date-time) | no | When it was created. |
created_by_name | string | no | Who created it (a person or a key's name). |
updated_at | string (date-time) | no | Its last change. |
credential | Credential or any or null | yes | The active credential, else the pending one, else null (always null for a federated destination). |
last_delivery | Delivery or any or null | yes | The newest delivery, or null. |
test_prefix | string or null | yes | A managed legacy feed's test prefix, set by EzyInsights staff: its connection test writes the feed's first real hourly file under this prefix instead of prefix, so a credential is proven without touching a live feed; deliveries never use it. Null on any other destination. Read-only with a key. See Managed legacy feeds. |
PATCH /v1/destinations/{id}
Change a destination
Name, schedule, format, compression, format options, columns, filter and, for a federated destination, its values. The store (provider, bucket, prefix, endpoint) cannot change: delete the destination and create another. A call that changes nothing writes nothing and answers 200. If-Match is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope destinations:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Request body
As application/json:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | Its name. at most 60 characters |
schedule | object or object or object | no | When a destination delivers. |
format | string | no | The file format. one of jsonl, csv, tsv, json, parquet, avro |
compression | string | no | The compression: gzip or none for every format; zstd only for Parquet (inside the file), once Parquet files are available.one of gzip, zstd, none |
format_options | FormatOptions | no | CSV's delimiter, header row and byte order mark; TSV's header row and byte order mark. In a TSV file, a tab or a line break inside a value is replaced by one space. Other formats take none of these. Every format takes evidence_text. |
columns | array of string or null | no | The columns to deliver, or null for all: flat column names for CSV and TSV, dot paths for JSON Lines and JSON. An unknown one is refused. |
filter | PushFilter | no | Which detections a destination delivers; every field optional, all given must hold. |
federation | object or object or object | no | A federated destination's values, from its setup steps; exactly its provider's fields. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | Changed, or already so. | application/json: Destination | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 413 | content_too_large: the body is larger than 64 KB (65,536 bytes). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Destination)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The destination's id (dst_…). |
name | string | no | Its name, 1 to 60 characters. |
provider | string | no | The storage provider. one of s3, s3_compatible, gcs, azure |
bucket | string | no | The bucket (or Azure container). |
prefix | string | no | The key prefix files are written under; empty or ending in /. |
region | string or null | yes | The region, where the provider has one. |
endpoint | string or null | yes | An S3-compatible store's address. |
storage_account | string or null | yes | Azure's storage account. |
auth_mode | string | no | federated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.one of federated, stored |
federation | object or object or object or any or null | yes | A federated destination's values, null until they are sent. |
format | string | no | The file format. one of jsonl, csv, tsv, json, parquet, avro |
compression | string | no | The files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.one of gzip, zstd, none |
format_options | FormatOptions | no | CSV's delimiter, header row and byte order mark; TSV's header row and byte order mark. In a TSV file, a tab or a line break inside a value is replaced by one space. Other formats take none of these. Every format takes evidence_text. |
format_options.delimiter optional | string | no | , or ; for CSV; a tab for TSV.one of ,, ;, |
format_options.header optional | boolean | no | A header row first. default true |
format_options.bom optional | boolean | no | A UTF-8 byte order mark first, for spreadsheets. default false |
format_options.evidence_text optional | boolean | no | Matched sentences, any format: beside each delivery whose rows include text detections, a JSON Lines side file of how each was matched, <name>-evidence-<NNNN>.jsonl.gz (plain .jsonl with compression none), a line each (TextEvidenceAnswer), listed in the manifest's evidence_files with the counts evidence_gone and evidence_unreadable. Only on a destination that carries text; never on a managed legacy feed. Refused otherwise with format_options.evidence_text named.default false |
schema_version | string | no | The detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).one of v1, legacy |
columns | array of string or null | yes | The columns delivered, or null for all: flat column names for CSV and TSV (as /v1/schema/detection lists them), dot paths for JSON Lines and JSON (see Deliveries). |
filter | PushFilter | no | Which detections a destination delivers; every field optional, all given must hold. |
filter.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
filter.min_band optional | string | no | The weakest strength delivered; max means text only reaches it.one of off, low, medium, high, max |
filter.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
filter.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
schedule | object or object or object | no | When a destination delivers. |
next_run_at | string (date-time) or null | yes | The next scheduled delivery; null while none is scheduled (setting up, paused). |
start_at | string (date-time) | no | Where the first delivery started. |
cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
cursor.seq | integer | no | The chunk's sequence number. |
cursor.row | integer | no | Rows of that chunk read. |
delivered_up_to | string (date-time) or null | yes | When the newest done delivery finished; null before the first. |
status | string | no | setting_up until it is first started. It stays active while a delivery retries; failing once a delivery has failed for good (24 hours after its first failure, or at once when the store refuses the credential or the address), and then nothing more is scheduled until it is resumed. disabled is not used for destinations today. See Deliveries.one of setting_up, active, paused, failing, disabled |
last_test_at | string (date-time) or null | yes | The last connection test. |
last_test_ok | boolean or null | yes | Whether it passed. |
last_test_error | string or null | yes | The provider's words when it failed. |
running_since | string (date-time) or null | yes | When the delivery running now started. |
failing_since | string (date-time) or null | yes | When it began failing. |
version | integer | no | Its configuration's version, also the ETag. |
created_at | string (date-time) | no | When it was created. |
created_by_name | string | no | Who created it (a person or a key's name). |
updated_at | string (date-time) | no | Its last change. |
credential | Credential or any or null | yes | The active credential, else the pending one, else null (always null for a federated destination). |
last_delivery | Delivery or any or null | yes | The newest delivery, or null. |
test_prefix | string or null | yes | A managed legacy feed's test prefix, set by EzyInsights staff: its connection test writes the feed's first real hourly file under this prefix instead of prefix, so a credential is proven without touching a live feed; deliveries never use it. Null on any other destination. Read-only with a key. See Managed legacy feeds. |
DELETE /v1/destinations/{id}
Delete a destination
Stops the destination and deletes it: a running delivery stops at its next step and uploads nothing more. Afterwards the destination is 404, also to a repeated DELETE. If-Match is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope destinations:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 204 | Deleted. The ETag is its last version. | none | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
GET /v1/destinations/{id}/setup
The setup steps
The provider's setup steps for a federated destination, filled in with this destination's values (its subject, the audience, the bucket and prefix), and the fields whose values you then send with PATCH as federation. A destination with stored credentials has no steps at the provider: both lists are empty, and its credential is sent with …/credential.
Authentication: A key or an access token (Authorization: Bearer …) with the scope destinations:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The steps and the fields. | application/json: SetupSteps | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (SetupSteps)
| Field | Type | Nullable | Description |
|---|---|---|---|
steps | array of object | no | The steps, in order. |
steps[].text | string | no | What to do. |
steps[].code optional | string | no | A command or policy to paste, filled in with this destination's values. |
steps[].copy_label optional | string | no | A label for the code. |
fields | array of object | no | The values to send with PATCH as federation. |
fields[].name | string | no | The field's name in federation. |
fields[].label | string | no | Its label. |
fields[].placeholder | string | no | An example value. |
fields[].pattern | string | no | The regular expression a value must match. |
POST /v1/destinations/{id}/credential
Add or replace the stored credential
Write-only: the credential is sealed, used for one test write (<prefix>_ezyinsights_test.json) and never returned or logged. When the test passes it becomes the active credential and the old one is retired; when it fails the old one stays and the answer carries the provider's words. The answer is 200 either way: read test.ok. Send Idempotency-Key so a retried timeout neither tests twice nor meets the one-pending rule; a repeat answers test: null. If-Match is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope destinations:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Idempotency-Key | header | string | no | 1 to 255 visible ASCII characters of your choosing, one per request you mean to make once. A repeat of the same request (method, path and body) with the same key within 24 hours makes nothing new and answers what the first made, as it is now, or 404 if it has since been deleted, with Idempotent-Replayed: true; a secret or a test result is never answered twice. While the first request still runs, a repeat is 409 (retry it in a moment). The same key with another request is 422. A request that was refused, or that has not answered within 5 minutes, leaves the key free. Keys are kept per API key, at most 1,000 in 24 hours: past that, a new key is 429 with Retry-After until the oldest of them is a day old (a repeat, or a request without the header, is still answered).at most 255 characters |
Request body
As application/json:
| Field | Type | Required | Description |
|---|
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The test, the credential now (never a value) and the destination. | application/json: CredentialReplaced | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag, Idempotent-Replayed |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 413 | content_too_large: the body is larger than 64 KB (65,536 bytes). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 422 | idempotency_key_reused: this Idempotency-Key was used in the last 24 hours with a different request (another body, path or method). Nothing was done. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 429 | rate_limited: more than 120 requests a minute for this key (Retry-After: 60), more than 10 tests and replays in the last hour for this destination or endpoint (Retry-After: 3600), or, with an Idempotency-Key, 1,000 keys used by this API key in the last 24 hours (Retry-After until the oldest of them is a day old). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (CredentialReplaced)
| Field | Type | Nullable | Description |
|---|---|---|---|
test | TestResult or any or null | yes | The test write; null on a repeated Idempotency-Key (a test is answered once). |
credential | Credential or any or null | yes | The active credential now (the new one when its test passed), else null. |
destination | Destination | no | A destination, never a secret. |
destination.id | string | no | The destination's id (dst_…). |
destination.name | string | no | Its name, 1 to 60 characters. |
destination.provider | string | no | The storage provider. one of s3, s3_compatible, gcs, azure |
destination.bucket | string | no | The bucket (or Azure container). |
destination.prefix | string | no | The key prefix files are written under; empty or ending in /. |
destination.region | string or null | yes | The region, where the provider has one. |
destination.endpoint | string or null | yes | An S3-compatible store's address. |
destination.storage_account | string or null | yes | Azure's storage account. |
destination.auth_mode | string | no | federated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.one of federated, stored |
destination.federation | object or object or object or any or null | yes | A federated destination's values, null until they are sent. |
destination.format | string | no | The file format. one of jsonl, csv, tsv, json, parquet, avro |
destination.compression | string | no | The files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.one of gzip, zstd, none |
destination.format_options | FormatOptions | no | CSV's delimiter, header row and byte order mark; TSV's header row and byte order mark. In a TSV file, a tab or a line break inside a value is replaced by one space. Other formats take none of these. Every format takes evidence_text. |
destination.format_options.delimiter optional | string | no | , or ; for CSV; a tab for TSV.one of ,, ;, |
destination.format_options.header optional | boolean | no | A header row first. default true |
destination.format_options.bom optional | boolean | no | A UTF-8 byte order mark first, for spreadsheets. default false |
destination.format_options.evidence_text optional | boolean | no | Matched sentences, any format: beside each delivery whose rows include text detections, a JSON Lines side file of how each was matched, <name>-evidence-<NNNN>.jsonl.gz (plain .jsonl with compression none), a line each (TextEvidenceAnswer), listed in the manifest's evidence_files with the counts evidence_gone and evidence_unreadable. Only on a destination that carries text; never on a managed legacy feed. Refused otherwise with format_options.evidence_text named.default false |
destination.schema_version | string | no | The detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).one of v1, legacy |
destination.columns | array of string or null | yes | The columns delivered, or null for all: flat column names for CSV and TSV (as /v1/schema/detection lists them), dot paths for JSON Lines and JSON (see Deliveries). |
destination.filter | PushFilter | no | Which detections a destination delivers; every field optional, all given must hold. |
destination.filter.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
destination.filter.min_band optional | string | no | The weakest strength delivered; max means text only reaches it.one of off, low, medium, high, max |
destination.filter.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
destination.filter.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
destination.schedule | object or object or object | no | When a destination delivers. |
destination.next_run_at | string (date-time) or null | yes | The next scheduled delivery; null while none is scheduled (setting up, paused). |
destination.start_at | string (date-time) | no | Where the first delivery started. |
destination.cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
destination.cursor.seq | integer | no | The chunk's sequence number. |
destination.cursor.row | integer | no | Rows of that chunk read. |
destination.delivered_up_to | string (date-time) or null | yes | When the newest done delivery finished; null before the first. |
destination.status | string | no | setting_up until it is first started. It stays active while a delivery retries; failing once a delivery has failed for good (24 hours after its first failure, or at once when the store refuses the credential or the address), and then nothing more is scheduled until it is resumed. disabled is not used for destinations today. See Deliveries.one of setting_up, active, paused, failing, disabled |
destination.last_test_at | string (date-time) or null | yes | The last connection test. |
destination.last_test_ok | boolean or null | yes | Whether it passed. |
destination.last_test_error | string or null | yes | The provider's words when it failed. |
destination.running_since | string (date-time) or null | yes | When the delivery running now started. |
destination.failing_since | string (date-time) or null | yes | When it began failing. |
destination.version | integer | no | Its configuration's version, also the ETag. |
destination.created_at | string (date-time) | no | When it was created. |
destination.created_by_name | string | no | Who created it (a person or a key's name). |
destination.updated_at | string (date-time) | no | Its last change. |
destination.credential | Credential or any or null | yes | The active credential, else the pending one, else null (always null for a federated destination). |
destination.last_delivery | Delivery or any or null | yes | The newest delivery, or null. |
destination.test_prefix | string or null | yes | A managed legacy feed's test prefix, set by EzyInsights staff: its connection test writes the feed's first real hourly file under this prefix instead of prefix, so a credential is proven without touching a live feed; deliveries never use it. Null on any other destination. Read-only with a key. See Managed legacy feeds. |
POST /v1/destinations/{id}/test
Test the connection
One test write with the active (else the pending) credential, or the federated identity; the answer is the attempt, with the provider's status and error code verbatim. At most 10 tests an hour per destination (429, Retry-After: 3600). If-Match is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope destinations:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The attempt. | application/json: TestResult | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 429 | rate_limited: more than 120 requests a minute for this key (Retry-After: 60), more than 10 tests and replays in the last hour for this destination or endpoint (Retry-After: 3600), or, with an Idempotency-Key, 1,000 keys used by this API key in the last 24 hours (Retry-After until the oldest of them is a day old). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (TestResult)
| Field | Type | Nullable | Description |
|---|---|---|---|
ok | boolean | no | Whether the write succeeded. |
status | integer or null | yes | The provider's HTTP status; null when it could not be reached. |
code | string or null | yes | The provider's error code. |
message | string or null | yes | The provider's error message. |
at | string (date-time) | no | When it was made. |
key | string or null | yes | The key written (<prefix>_ezyinsights_test.json), when it succeeded. |
latency_ms | integer | no | How long it took. |
POST /v1/destinations/{id}/pause
Pause a destination
An active destination stops delivering until it is resumed. If-Match is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope destinations:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The destination now. | application/json: Destination | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Destination)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The destination's id (dst_…). |
name | string | no | Its name, 1 to 60 characters. |
provider | string | no | The storage provider. one of s3, s3_compatible, gcs, azure |
bucket | string | no | The bucket (or Azure container). |
prefix | string | no | The key prefix files are written under; empty or ending in /. |
region | string or null | yes | The region, where the provider has one. |
endpoint | string or null | yes | An S3-compatible store's address. |
storage_account | string or null | yes | Azure's storage account. |
auth_mode | string | no | federated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.one of federated, stored |
federation | object or object or object or any or null | yes | A federated destination's values, null until they are sent. |
format | string | no | The file format. one of jsonl, csv, tsv, json, parquet, avro |
compression | string | no | The files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.one of gzip, zstd, none |
format_options | FormatOptions | no | CSV's delimiter, header row and byte order mark; TSV's header row and byte order mark. In a TSV file, a tab or a line break inside a value is replaced by one space. Other formats take none of these. Every format takes evidence_text. |
format_options.delimiter optional | string | no | , or ; for CSV; a tab for TSV.one of ,, ;, |
format_options.header optional | boolean | no | A header row first. default true |
format_options.bom optional | boolean | no | A UTF-8 byte order mark first, for spreadsheets. default false |
format_options.evidence_text optional | boolean | no | Matched sentences, any format: beside each delivery whose rows include text detections, a JSON Lines side file of how each was matched, <name>-evidence-<NNNN>.jsonl.gz (plain .jsonl with compression none), a line each (TextEvidenceAnswer), listed in the manifest's evidence_files with the counts evidence_gone and evidence_unreadable. Only on a destination that carries text; never on a managed legacy feed. Refused otherwise with format_options.evidence_text named.default false |
schema_version | string | no | The detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).one of v1, legacy |
columns | array of string or null | yes | The columns delivered, or null for all: flat column names for CSV and TSV (as /v1/schema/detection lists them), dot paths for JSON Lines and JSON (see Deliveries). |
filter | PushFilter | no | Which detections a destination delivers; every field optional, all given must hold. |
filter.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
filter.min_band optional | string | no | The weakest strength delivered; max means text only reaches it.one of off, low, medium, high, max |
filter.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
filter.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
schedule | object or object or object | no | When a destination delivers. |
next_run_at | string (date-time) or null | yes | The next scheduled delivery; null while none is scheduled (setting up, paused). |
start_at | string (date-time) | no | Where the first delivery started. |
cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
cursor.seq | integer | no | The chunk's sequence number. |
cursor.row | integer | no | Rows of that chunk read. |
delivered_up_to | string (date-time) or null | yes | When the newest done delivery finished; null before the first. |
status | string | no | setting_up until it is first started. It stays active while a delivery retries; failing once a delivery has failed for good (24 hours after its first failure, or at once when the store refuses the credential or the address), and then nothing more is scheduled until it is resumed. disabled is not used for destinations today. See Deliveries.one of setting_up, active, paused, failing, disabled |
last_test_at | string (date-time) or null | yes | The last connection test. |
last_test_ok | boolean or null | yes | Whether it passed. |
last_test_error | string or null | yes | The provider's words when it failed. |
running_since | string (date-time) or null | yes | When the delivery running now started. |
failing_since | string (date-time) or null | yes | When it began failing. |
version | integer | no | Its configuration's version, also the ETag. |
created_at | string (date-time) | no | When it was created. |
created_by_name | string | no | Who created it (a person or a key's name). |
updated_at | string (date-time) | no | Its last change. |
credential | Credential or any or null | yes | The active credential, else the pending one, else null (always null for a federated destination). |
last_delivery | Delivery or any or null | yes | The newest delivery, or null. |
test_prefix | string or null | yes | A managed legacy feed's test prefix, set by EzyInsights staff: its connection test writes the feed's first real hourly file under this prefix instead of prefix, so a credential is proven without touching a live feed; deliveries never use it. Null on any other destination. Read-only with a key. See Managed legacy feeds. |
POST /v1/destinations/{id}/resume
Start or resume a destination
From setting_up, the first start, which needs a passed connection test (409 state_conflict otherwise); from paused; and from failing or disabled, where the system stopped it, from where it stopped. Starting, or resuming after a failure, queues a delivery at once. If-Match is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope destinations:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The destination now. | application/json: Destination | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Destination)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The destination's id (dst_…). |
name | string | no | Its name, 1 to 60 characters. |
provider | string | no | The storage provider. one of s3, s3_compatible, gcs, azure |
bucket | string | no | The bucket (or Azure container). |
prefix | string | no | The key prefix files are written under; empty or ending in /. |
region | string or null | yes | The region, where the provider has one. |
endpoint | string or null | yes | An S3-compatible store's address. |
storage_account | string or null | yes | Azure's storage account. |
auth_mode | string | no | federated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.one of federated, stored |
federation | object or object or object or any or null | yes | A federated destination's values, null until they are sent. |
format | string | no | The file format. one of jsonl, csv, tsv, json, parquet, avro |
compression | string | no | The files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.one of gzip, zstd, none |
format_options | FormatOptions | no | CSV's delimiter, header row and byte order mark; TSV's header row and byte order mark. In a TSV file, a tab or a line break inside a value is replaced by one space. Other formats take none of these. Every format takes evidence_text. |
format_options.delimiter optional | string | no | , or ; for CSV; a tab for TSV.one of ,, ;, |
format_options.header optional | boolean | no | A header row first. default true |
format_options.bom optional | boolean | no | A UTF-8 byte order mark first, for spreadsheets. default false |
format_options.evidence_text optional | boolean | no | Matched sentences, any format: beside each delivery whose rows include text detections, a JSON Lines side file of how each was matched, <name>-evidence-<NNNN>.jsonl.gz (plain .jsonl with compression none), a line each (TextEvidenceAnswer), listed in the manifest's evidence_files with the counts evidence_gone and evidence_unreadable. Only on a destination that carries text; never on a managed legacy feed. Refused otherwise with format_options.evidence_text named.default false |
schema_version | string | no | The detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).one of v1, legacy |
columns | array of string or null | yes | The columns delivered, or null for all: flat column names for CSV and TSV (as /v1/schema/detection lists them), dot paths for JSON Lines and JSON (see Deliveries). |
filter | PushFilter | no | Which detections a destination delivers; every field optional, all given must hold. |
filter.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
filter.min_band optional | string | no | The weakest strength delivered; max means text only reaches it.one of off, low, medium, high, max |
filter.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
filter.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
schedule | object or object or object | no | When a destination delivers. |
next_run_at | string (date-time) or null | yes | The next scheduled delivery; null while none is scheduled (setting up, paused). |
start_at | string (date-time) | no | Where the first delivery started. |
cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
cursor.seq | integer | no | The chunk's sequence number. |
cursor.row | integer | no | Rows of that chunk read. |
delivered_up_to | string (date-time) or null | yes | When the newest done delivery finished; null before the first. |
status | string | no | setting_up until it is first started. It stays active while a delivery retries; failing once a delivery has failed for good (24 hours after its first failure, or at once when the store refuses the credential or the address), and then nothing more is scheduled until it is resumed. disabled is not used for destinations today. See Deliveries.one of setting_up, active, paused, failing, disabled |
last_test_at | string (date-time) or null | yes | The last connection test. |
last_test_ok | boolean or null | yes | Whether it passed. |
last_test_error | string or null | yes | The provider's words when it failed. |
running_since | string (date-time) or null | yes | When the delivery running now started. |
failing_since | string (date-time) or null | yes | When it began failing. |
version | integer | no | Its configuration's version, also the ETag. |
created_at | string (date-time) | no | When it was created. |
created_by_name | string | no | Who created it (a person or a key's name). |
updated_at | string (date-time) | no | Its last change. |
credential | Credential or any or null | yes | The active credential, else the pending one, else null (always null for a federated destination). |
last_delivery | Delivery or any or null | yes | The newest delivery, or null. |
test_prefix | string or null | yes | A managed legacy feed's test prefix, set by EzyInsights staff: its connection test writes the feed's first real hourly file under this prefix instead of prefix, so a credential is proven without touching a live feed; deliveries never use it. Null on any other destination. Read-only with a key. See Managed legacy feeds. |
POST /v1/destinations/{id}/run-now
Deliver now
Starts the next delivery of an active destination now; 409 while one is running. If-Match is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope destinations:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The destination now. | application/json: Destination | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Destination)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The destination's id (dst_…). |
name | string | no | Its name, 1 to 60 characters. |
provider | string | no | The storage provider. one of s3, s3_compatible, gcs, azure |
bucket | string | no | The bucket (or Azure container). |
prefix | string | no | The key prefix files are written under; empty or ending in /. |
region | string or null | yes | The region, where the provider has one. |
endpoint | string or null | yes | An S3-compatible store's address. |
storage_account | string or null | yes | Azure's storage account. |
auth_mode | string | no | federated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.one of federated, stored |
federation | object or object or object or any or null | yes | A federated destination's values, null until they are sent. |
format | string | no | The file format. one of jsonl, csv, tsv, json, parquet, avro |
compression | string | no | The files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.one of gzip, zstd, none |
format_options | FormatOptions | no | CSV's delimiter, header row and byte order mark; TSV's header row and byte order mark. In a TSV file, a tab or a line break inside a value is replaced by one space. Other formats take none of these. Every format takes evidence_text. |
format_options.delimiter optional | string | no | , or ; for CSV; a tab for TSV.one of ,, ;, |
format_options.header optional | boolean | no | A header row first. default true |
format_options.bom optional | boolean | no | A UTF-8 byte order mark first, for spreadsheets. default false |
format_options.evidence_text optional | boolean | no | Matched sentences, any format: beside each delivery whose rows include text detections, a JSON Lines side file of how each was matched, <name>-evidence-<NNNN>.jsonl.gz (plain .jsonl with compression none), a line each (TextEvidenceAnswer), listed in the manifest's evidence_files with the counts evidence_gone and evidence_unreadable. Only on a destination that carries text; never on a managed legacy feed. Refused otherwise with format_options.evidence_text named.default false |
schema_version | string | no | The detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).one of v1, legacy |
columns | array of string or null | yes | The columns delivered, or null for all: flat column names for CSV and TSV (as /v1/schema/detection lists them), dot paths for JSON Lines and JSON (see Deliveries). |
filter | PushFilter | no | Which detections a destination delivers; every field optional, all given must hold. |
filter.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
filter.min_band optional | string | no | The weakest strength delivered; max means text only reaches it.one of off, low, medium, high, max |
filter.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
filter.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
schedule | object or object or object | no | When a destination delivers. |
next_run_at | string (date-time) or null | yes | The next scheduled delivery; null while none is scheduled (setting up, paused). |
start_at | string (date-time) | no | Where the first delivery started. |
cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
cursor.seq | integer | no | The chunk's sequence number. |
cursor.row | integer | no | Rows of that chunk read. |
delivered_up_to | string (date-time) or null | yes | When the newest done delivery finished; null before the first. |
status | string | no | setting_up until it is first started. It stays active while a delivery retries; failing once a delivery has failed for good (24 hours after its first failure, or at once when the store refuses the credential or the address), and then nothing more is scheduled until it is resumed. disabled is not used for destinations today. See Deliveries.one of setting_up, active, paused, failing, disabled |
last_test_at | string (date-time) or null | yes | The last connection test. |
last_test_ok | boolean or null | yes | Whether it passed. |
last_test_error | string or null | yes | The provider's words when it failed. |
running_since | string (date-time) or null | yes | When the delivery running now started. |
failing_since | string (date-time) or null | yes | When it began failing. |
version | integer | no | Its configuration's version, also the ETag. |
created_at | string (date-time) | no | When it was created. |
created_by_name | string | no | Who created it (a person or a key's name). |
updated_at | string (date-time) | no | Its last change. |
credential | Credential or any or null | yes | The active credential, else the pending one, else null (always null for a federated destination). |
last_delivery | Delivery or any or null | yes | The newest delivery, or null. |
test_prefix | string or null | yes | A managed legacy feed's test prefix, set by EzyInsights staff: its connection test writes the feed's first real hourly file under this prefix instead of prefix, so a credential is proven without touching a live feed; deliveries never use it. Null on any other destination. Read-only with a key. See Managed legacy feeds. |
GET /v1/destinations/{id}/deliveries
The delivery log
The destination's deliveries, newest first, each with its rows, parts, bytes, manifest and, when it failed, the provider's words. Follow next_cursor while has_more is true (a page can be empty).
Authentication: A key or an access token (Authorization: Bearer …) with the scope destinations:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
limit | query | integer | no | Rows in a page, 1 to 100; 100 when not given. 1 to 100; default 100 |
cursor | query | string | no | The next_cursor of a previous page of this log; the page after it. A value this endpoint did not give is 400. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | A page of the log. | application/json: DeliveriesPage | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (DeliveriesPage)
| Field | Type | Nullable | Description |
|---|---|---|---|
data | array of Delivery | no | The deliveries, newest first. |
data[].id | string | no | The delivery's id (dlv_…). |
data[].status | string | no | Where it is; empty when there was nothing to deliver.one of planned, rendering, uploading, done, empty, failed |
data[].from | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
data[].from.seq | integer | no | The chunk's sequence number. |
data[].from.row | integer | no | Rows of that chunk read. |
data[].to | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
data[].to.seq | integer | no | The chunk's sequence number. |
data[].to.row | integer | no | Rows of that chunk read. |
data[].rows | integer or null | yes | Detections delivered. |
data[].parts | integer or null | yes | Files written. |
data[].bytes | integer or null | yes | Bytes written. |
data[].manifest_key | string or null | yes | The manifest's key in your bucket; it lists the parts. |
data[].attempts | integer | no | Failed attempts so far. |
data[].first_failed_at | string (date-time) or null | yes | The first failed attempt. |
data[].error | string or null | yes | The provider's status and error code, verbatim. |
data[].trigger | string | no | What started it. one of schedule, run_now, resume |
data[].started_at | string (date-time) | no | When it started. |
data[].finished_at | string (date-time) or null | yes | When it finished. |
data[].step | object or any or null | yes | While rendering or uploading, the part being worked on and how many are planned so far. |
next_cursor | string or null | yes | The next page's cursor, or null. |
has_more | boolean | no | True when there may be another page (which can be empty). |
GET /v1/webhooks
The subscription’s webhook endpoints
The key's subscription's endpoints, newest first, at most 10, each with its newest message (last_message). One page: next_cursor is always null.
Authentication: A key or an access token (Authorization: Bearer …) with the scope webhooks:manage.
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The endpoints. | application/json: WebhooksPage | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (WebhooksPage)
| Field | Type | Nullable | Description |
|---|---|---|---|
data | array of Webhook | no | The endpoints, newest first. |
data[].id | string | no | The endpoint's id (whk_…). |
data[].url | string | no | Where messages are sent (a public https address). |
data[].rule | WebhookRule | no | What an endpoint receives; every field optional, all given must hold. |
data[].rule.events optional | array of string | no | New detections, changed ones, or both (the default). each one of created, updated |
data[].rule.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
data[].rule.min_band optional | string | no | The weakest strength sent. one of off, low, medium, high, max |
data[].rule.customer optional | boolean | no | Customers only (true) or non-customers only (false); only once the subscription has a Sites list with customers. |
data[].rule.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
data[].rule.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
data[].status | string | no | failing while messages fail; disabled when the system stopped it after 3 days of failing.one of active, paused, failing, disabled |
data[].failing_since | string (date-time) or null | yes | When it began failing. |
data[].secret_set_at | string (date-time) | no | When the signing secret was made. |
data[].secret_set_by_name | string | no | Who made it (a person or a key's name). |
data[].previous_secret_until | string (date-time) or null | yes | After a rotation, until when messages are also signed with the old secret. |
data[].cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
data[].cursor.seq | integer | no | The chunk's sequence number. |
data[].cursor.row | integer | no | Rows of that chunk read. |
data[].version | integer | no | Its configuration's version, also the ETag. |
data[].created_at | string (date-time) | no | When it was created. |
data[].created_by_name | string | no | Who created it (a person or a key's name). |
data[].updated_at | string (date-time) | no | Its last change. |
data[].last_message | Message or any or null | yes | The newest message, or null. |
next_cursor | any or null | yes | Always null (one page). |
has_more | boolean | no | Always false. |
POST /v1/webhooks
Create a webhook endpoint
An active endpoint, receiving what is detected after it is created. The URL must be a public https address. The signing secret (whsec_…) is in this answer only: store it. A subscription has at most 10 endpoints (409 limit_reached). Send Idempotency-Key so a retried timeout does not create twice; a repeat answers the endpoint with secret: null.
Authentication: A key or an access token (Authorization: Bearer …) with the scope webhooks:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | no | 1 to 255 visible ASCII characters of your choosing, one per request you mean to make once. A repeat of the same request (method, path and body) with the same key within 24 hours makes nothing new and answers what the first made, as it is now, or 404 if it has since been deleted, with Idempotent-Replayed: true; a secret or a test result is never answered twice. While the first request still runs, a repeat is 409 (retry it in a moment). The same key with another request is 422. A request that was refused, or that has not answered within 5 minutes, leaves the key free. Keys are kept per API key, at most 1,000 in 24 hours: past that, a new key is 429 with Retry-After until the oldest of them is a day old (a repeat, or a request without the header, is still answered).at most 255 characters |
Request body
As application/json:
| Field | Type | Required | Description |
|---|---|---|---|
url | string | yes | A public https address; not an IP address, not a private or local name. |
rule | WebhookRule | no | What an endpoint receives; every field optional, all given must hold. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 201 | Created, with its signing secret; or, with an Idempotency-Key already used for this request in the last 24 hours, the endpoint it created, as it is now, with secret: null. | application/json: WebhookWithSecret | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag, Idempotent-Replayed |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 413 | content_too_large: the body is larger than 64 KB (65,536 bytes). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 422 | idempotency_key_reused: this Idempotency-Key was used in the last 24 hours with a different request (another body, path or method). Nothing was done. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 429 | rate_limited: more than 120 requests a minute for this key (Retry-After: 60), more than 10 tests and replays in the last hour for this destination or endpoint (Retry-After: 3600), or, with an Idempotency-Key, 1,000 keys used by this API key in the last 24 hours (Retry-After until the oldest of them is a day old). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
201 body (WebhookWithSecret)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The endpoint's id (whk_…). |
url | string | no | Where messages are sent (a public https address). |
rule | WebhookRule | no | What an endpoint receives; every field optional, all given must hold. |
rule.events optional | array of string | no | New detections, changed ones, or both (the default). each one of created, updated |
rule.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
rule.min_band optional | string | no | The weakest strength sent. one of off, low, medium, high, max |
rule.customer optional | boolean | no | Customers only (true) or non-customers only (false); only once the subscription has a Sites list with customers. |
rule.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
rule.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
status | string | no | failing while messages fail; disabled when the system stopped it after 3 days of failing.one of active, paused, failing, disabled |
failing_since | string (date-time) or null | yes | When it began failing. |
secret_set_at | string (date-time) | no | When the signing secret was made. |
secret_set_by_name | string | no | Who made it (a person or a key's name). |
previous_secret_until | string (date-time) or null | yes | After a rotation, until when messages are also signed with the old secret. |
cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
cursor.seq | integer | no | The chunk's sequence number. |
cursor.row | integer | no | Rows of that chunk read. |
version | integer | no | Its configuration's version, also the ETag. |
created_at | string (date-time) | no | When it was created. |
created_by_name | string | no | Who created it (a person or a key's name). |
updated_at | string (date-time) | no | Its last change. |
last_message | Message or any or null | yes | The newest message, or null. |
secret | string or null | yes | The signing secret (whsec_…), returned once, on the first call; null when an Idempotency-Key repeats it. |
GET /v1/webhooks/{id}
One webhook endpoint
The endpoint and its newest message; never its secret. The ETag is its version.
Authentication: A key or an access token (Authorization: Bearer …) with the scope webhooks:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The endpoint. | application/json: Webhook | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Webhook)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The endpoint's id (whk_…). |
url | string | no | Where messages are sent (a public https address). |
rule | WebhookRule | no | What an endpoint receives; every field optional, all given must hold. |
rule.events optional | array of string | no | New detections, changed ones, or both (the default). each one of created, updated |
rule.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
rule.min_band optional | string | no | The weakest strength sent. one of off, low, medium, high, max |
rule.customer optional | boolean | no | Customers only (true) or non-customers only (false); only once the subscription has a Sites list with customers. |
rule.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
rule.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
status | string | no | failing while messages fail; disabled when the system stopped it after 3 days of failing.one of active, paused, failing, disabled |
failing_since | string (date-time) or null | yes | When it began failing. |
secret_set_at | string (date-time) | no | When the signing secret was made. |
secret_set_by_name | string | no | Who made it (a person or a key's name). |
previous_secret_until | string (date-time) or null | yes | After a rotation, until when messages are also signed with the old secret. |
cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
cursor.seq | integer | no | The chunk's sequence number. |
cursor.row | integer | no | Rows of that chunk read. |
version | integer | no | Its configuration's version, also the ETag. |
created_at | string (date-time) | no | When it was created. |
created_by_name | string | no | Who created it (a person or a key's name). |
updated_at | string (date-time) | no | Its last change. |
last_message | Message or any or null | yes | The newest message, or null. |
PATCH /v1/webhooks/{id}
Change a webhook endpoint
Its URL and rule. A message already being sent keeps the rule it was made with. A call that changes nothing writes nothing and answers 200. If-Match is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope webhooks:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Request body
As application/json:
| Field | Type | Required | Description |
|---|---|---|---|
url | string | no | A public https address. |
rule | WebhookRule | no | What an endpoint receives; every field optional, all given must hold. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | Changed, or already so. | application/json: Webhook | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 413 | content_too_large: the body is larger than 64 KB (65,536 bytes). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Webhook)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The endpoint's id (whk_…). |
url | string | no | Where messages are sent (a public https address). |
rule | WebhookRule | no | What an endpoint receives; every field optional, all given must hold. |
rule.events optional | array of string | no | New detections, changed ones, or both (the default). each one of created, updated |
rule.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
rule.min_band optional | string | no | The weakest strength sent. one of off, low, medium, high, max |
rule.customer optional | boolean | no | Customers only (true) or non-customers only (false); only once the subscription has a Sites list with customers. |
rule.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
rule.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
status | string | no | failing while messages fail; disabled when the system stopped it after 3 days of failing.one of active, paused, failing, disabled |
failing_since | string (date-time) or null | yes | When it began failing. |
secret_set_at | string (date-time) | no | When the signing secret was made. |
secret_set_by_name | string | no | Who made it (a person or a key's name). |
previous_secret_until | string (date-time) or null | yes | After a rotation, until when messages are also signed with the old secret. |
cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
cursor.seq | integer | no | The chunk's sequence number. |
cursor.row | integer | no | Rows of that chunk read. |
version | integer | no | Its configuration's version, also the ETag. |
created_at | string (date-time) | no | When it was created. |
created_by_name | string | no | Who created it (a person or a key's name). |
updated_at | string (date-time) | no | Its last change. |
last_message | Message or any or null | yes | The newest message, or null. |
DELETE /v1/webhooks/{id}
Delete a webhook endpoint
Nothing more is sent; a message being sent is dropped. Afterwards the endpoint is 404, also to a repeated DELETE. If-Match is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope webhooks:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 204 | Deleted. The ETag is its last version. | none | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
POST /v1/webhooks/{id}/rotate-secret
Rotate the signing secret
A new signing secret, in this answer only. For 24 hours (previous_secret_until) every message is also signed with the old one, so you can switch without losing a message. Send Idempotency-Key so a retried timeout does not rotate twice; a repeat answers secret: null. If-Match is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope webhooks:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Idempotency-Key | header | string | no | 1 to 255 visible ASCII characters of your choosing, one per request you mean to make once. A repeat of the same request (method, path and body) with the same key within 24 hours makes nothing new and answers what the first made, as it is now, or 404 if it has since been deleted, with Idempotent-Replayed: true; a secret or a test result is never answered twice. While the first request still runs, a repeat is 409 (retry it in a moment). The same key with another request is 422. A request that was refused, or that has not answered within 5 minutes, leaves the key free. Keys are kept per API key, at most 1,000 in 24 hours: past that, a new key is 429 with Retry-After until the oldest of them is a day old (a repeat, or a request without the header, is still answered).at most 255 characters |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The endpoint with its new secret; or, for a repeated Idempotency-Key, the endpoint now with secret: null. | application/json: WebhookWithSecret | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag, Idempotent-Replayed |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 413 | content_too_large: the body is larger than 64 KB (65,536 bytes). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 422 | idempotency_key_reused: this Idempotency-Key was used in the last 24 hours with a different request (another body, path or method). Nothing was done. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 429 | rate_limited: more than 120 requests a minute for this key (Retry-After: 60), more than 10 tests and replays in the last hour for this destination or endpoint (Retry-After: 3600), or, with an Idempotency-Key, 1,000 keys used by this API key in the last 24 hours (Retry-After until the oldest of them is a day old). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (WebhookWithSecret)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The endpoint's id (whk_…). |
url | string | no | Where messages are sent (a public https address). |
rule | WebhookRule | no | What an endpoint receives; every field optional, all given must hold. |
rule.events optional | array of string | no | New detections, changed ones, or both (the default). each one of created, updated |
rule.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
rule.min_band optional | string | no | The weakest strength sent. one of off, low, medium, high, max |
rule.customer optional | boolean | no | Customers only (true) or non-customers only (false); only once the subscription has a Sites list with customers. |
rule.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
rule.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
status | string | no | failing while messages fail; disabled when the system stopped it after 3 days of failing.one of active, paused, failing, disabled |
failing_since | string (date-time) or null | yes | When it began failing. |
secret_set_at | string (date-time) | no | When the signing secret was made. |
secret_set_by_name | string | no | Who made it (a person or a key's name). |
previous_secret_until | string (date-time) or null | yes | After a rotation, until when messages are also signed with the old secret. |
cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
cursor.seq | integer | no | The chunk's sequence number. |
cursor.row | integer | no | Rows of that chunk read. |
version | integer | no | Its configuration's version, also the ETag. |
created_at | string (date-time) | no | When it was created. |
created_by_name | string | no | Who created it (a person or a key's name). |
updated_at | string (date-time) | no | Its last change. |
last_message | Message or any or null | yes | The newest message, or null. |
secret | string or null | yes | The signing secret (whsec_…), returned once, on the first call; null when an Idempotency-Key repeats it. |
POST /v1/webhooks/{id}/pause
Pause a webhook endpoint
Nothing is sent until it is resumed; a message being sent waits, and its three days stop counting. If-Match is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope webhooks:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The endpoint now. | application/json: Webhook | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Webhook)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The endpoint's id (whk_…). |
url | string | no | Where messages are sent (a public https address). |
rule | WebhookRule | no | What an endpoint receives; every field optional, all given must hold. |
rule.events optional | array of string | no | New detections, changed ones, or both (the default). each one of created, updated |
rule.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
rule.min_band optional | string | no | The weakest strength sent. one of off, low, medium, high, max |
rule.customer optional | boolean | no | Customers only (true) or non-customers only (false); only once the subscription has a Sites list with customers. |
rule.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
rule.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
status | string | no | failing while messages fail; disabled when the system stopped it after 3 days of failing.one of active, paused, failing, disabled |
failing_since | string (date-time) or null | yes | When it began failing. |
secret_set_at | string (date-time) | no | When the signing secret was made. |
secret_set_by_name | string | no | Who made it (a person or a key's name). |
previous_secret_until | string (date-time) or null | yes | After a rotation, until when messages are also signed with the old secret. |
cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
cursor.seq | integer | no | The chunk's sequence number. |
cursor.row | integer | no | Rows of that chunk read. |
version | integer | no | Its configuration's version, also the ETag. |
created_at | string (date-time) | no | When it was created. |
created_by_name | string | no | Who created it (a person or a key's name). |
updated_at | string (date-time) | no | Its last change. |
last_message | Message or any or null | yes | The newest message, or null. |
POST /v1/webhooks/{id}/resume
Resume a webhook endpoint
From paused, and from failing or disabled, where the system stopped it, from where it stopped. If-Match is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope webhooks:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The endpoint now. | application/json: Webhook | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Webhook)
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | The endpoint's id (whk_…). |
url | string | no | Where messages are sent (a public https address). |
rule | WebhookRule | no | What an endpoint receives; every field optional, all given must hold. |
rule.events optional | array of string | no | New detections, changed ones, or both (the default). each one of created, updated |
rule.content_types optional | array of string | no | A subset of what the subscription carries. each one of text, image |
rule.min_band optional | string | no | The weakest strength sent. one of off, low, medium, high, max |
rule.customer optional | boolean | no | Customers only (true) or non-customers only (false); only once the subscription has a Sites list with customers. |
rule.domains optional | array of string | no | Registrable domains, at most 50. at most 50 values |
rule.publisher_ids optional | array of integer | no | Publisher ids, at most 50. at most 50 values |
status | string | no | failing while messages fail; disabled when the system stopped it after 3 days of failing.one of active, paused, failing, disabled |
failing_since | string (date-time) or null | yes | When it began failing. |
secret_set_at | string (date-time) | no | When the signing secret was made. |
secret_set_by_name | string | no | Who made it (a person or a key's name). |
previous_secret_until | string (date-time) or null | yes | After a rotation, until when messages are also signed with the old secret. |
cursor | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
cursor.seq | integer | no | The chunk's sequence number. |
cursor.row | integer | no | Rows of that chunk read. |
version | integer | no | Its configuration's version, also the ETag. |
created_at | string (date-time) | no | When it was created. |
created_by_name | string | no | Who created it (a person or a key's name). |
updated_at | string (date-time) | no | Its last change. |
last_message | Message or any or null | yes | The newest message, or null. |
POST /v1/webhooks/{id}/test
Send a test message
One message holding one obviously fake detection, signed as every message is, sent now; the answer is the attempt. At most 10 tests and replays an hour per endpoint (429, Retry-After: 3600). If-Match is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope webhooks:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The attempt. | application/json: Attempt | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 429 | rate_limited: more than 120 requests a minute for this key (Retry-After: 60), more than 10 tests and replays in the last hour for this destination or endpoint (Retry-After: 3600), or, with an Idempotency-Key, 1,000 keys used by this API key in the last 24 hours (Retry-After until the oldest of them is a day old). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Attempt)
| Field | Type | Nullable | Description |
|---|---|---|---|
ok | boolean | no | Whether your endpoint accepted it (a 2xx). |
status | integer or null | yes | Your endpoint's HTTP status; null when it could not be reached. |
latency_ms | integer | no | How long it took. |
at | string (date-time) | no | When it was sent. |
error | string or null | yes | Why it failed. |
message_id | string | no | The message recorded for it, in the log. |
GET /v1/webhooks/{id}/messages
The message log
The endpoint's messages, newest first: batches, tests and replays, each with its last attempt. Follow next_cursor while has_more is true (a page can be empty).
Authentication: A key or an access token (Authorization: Bearer …) with the scope webhooks:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
limit | query | integer | no | Rows in a page, 1 to 100; 100 when not given. 1 to 100; default 100 |
cursor | query | string | no | The next_cursor of a previous page of this log; the page after it. A value this endpoint did not give is 400. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | A page of the log. | application/json: MessagesPage | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 429 | rate_limited: more than 120 requests a minute for this key, or too many requests with key ids not recently seen from this address. Retry after Retry-After seconds. The rate-limit headers are sent only with the first, when the credential was verified; the second comes before any verification. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (MessagesPage)
| Field | Type | Nullable | Description |
|---|---|---|---|
data | array of Message | no | The messages, newest first. |
data[].id | string | no | The message's id (msg_…), sent as webhook-id (a replay sends its original's). |
data[].kind | string | no | Detections, a test, or a message sent again. one of batch, test, replay |
data[].replay_of | string or null | yes | The original message of a replay. |
data[].from | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
data[].from.seq | integer | no | The chunk's sequence number. |
data[].from.row | integer | no | Rows of that chunk read. |
data[].to | StreamPosition | no | A position in the subscription's change stream (a chunk and the rows of it read). |
data[].to.seq | integer | no | The chunk's sequence number. |
data[].to.row | integer | no | Rows of that chunk read. |
data[].detections | integer | no | Detections in it. |
data[].status | string | no | pending while it is being sent (with retries), then delivered or failed.one of pending, delivered, failed |
data[].attempts | integer | no | Attempts so far. |
data[].last_status | integer or null | yes | Your endpoint's HTTP status at the last attempt. |
data[].last_latency_ms | integer or null | yes | How long the last attempt took. |
data[].last_error | string or null | yes | Why the last attempt failed. |
data[].next_attempt_at | string (date-time) or null | yes | The next retry of a pending message. |
data[].first_failed_at | string (date-time) or null | yes | The first failed attempt. |
data[].created_at | string (date-time) | no | When it was made. |
data[].delivered_at | string (date-time) or null | yes | When your endpoint accepted it. |
next_cursor | string or null | yes | The next page's cursor, or null. |
has_more | boolean | no | True when there may be another page (which can be empty). |
POST /v1/webhooks/{id}/messages/{message_id}/replay
Send a message again
A delivered or failed message sent again now, with its original webhook-id and the same body; the answer is the attempt. A message still being sent is 409. At most 10 tests and replays an hour per endpoint (429, Retry-After: 3600). If-Match (the endpoint's) is optional.
Authentication: A key or an access token (Authorization: Bearer …) with the scope webhooks:manage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | A webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is. |
message_id | path | string | yes | A message of this endpoint (msg_…), from its log. |
If-Match | header | string | no | The destination's or endpoint's ETag as the call last saw it ("7"). Optional: when it no longer matches (someone changed it in the app or by another script), the call does nothing and answers 412 with the ETag now. One strong tag only: a weak tag (W/"7") never matches (412), a list of tags is 400, and * makes the call unconditional. |
Responses
| Status | Meaning | Body | Headers |
|---|---|---|---|
| 200 | The attempt. | application/json: Attempt | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 400 | invalid_request: a parameter is unknown, repeated, empty or out of its range; a cursor this endpoint did not give; a filter naming a subscription or content type outside the key's scope; a malformed id. The credential was verified, so the rate-limit headers are sent. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 401 | unauthorized: no credential, or one that is malformed, unknown, expired or revoked. | application/problem+json: Problem | X-Request-Id, Cache-Control, WWW-Authenticate |
| 403 | forbidden: the API is suspended for the key's subscription, the key may not be used from this address, or the credential lacks the endpoint's scope. The rate-limit headers are sent only with the last, once the credential was verified and usable. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 404 | not_found: no such destination, webhook endpoint or message for this key. Another subscription's, a deleted one and an unknown id read the same. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 405 | method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer. | application/problem+json: Problem | X-Request-Id, Cache-Control, Allow |
| 409 | limit_reached: the subscription has 10 destinations or 10 endpoints, or a first delivery would be too large (the detail gives the estimate). state_conflict: the call does not fit the state (a start before a passed test, a run while one is running, a pause of a paused one, a credential already being tested, a credential for a federated destination), someone changed it while the call ran (read it again and retry), or a request with the same Idempotency-Key is still in progress (retry it in a moment). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 412 | precondition_failed: the destination or endpoint changed since the If-Match version; nothing was done. The ETag is its version now: read it again, then retry. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag |
| 429 | rate_limited: more than 120 requests a minute for this key (Retry-After: 60), more than 10 tests and replays in the last hour for this destination or endpoint (Retry-After: 3600), or, with an Idempotency-Key, 1,000 keys used by this API key in the last 24 hours (Retry-After until the oldest of them is a day old). | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After |
| 500 | internal: something went wrong on our side. Retry with backoff. The rate-limit headers are sent when the credential had been verified before the fault. | application/problem+json: Problem | X-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy |
| 503 | unavailable: the API cannot verify credentials right now, or our data store is restarting (a deploy; then Retry-After is 2 and the rate-limit headers are sent). Retry with backoff. | application/problem+json: Problem | X-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy |
200 body (Attempt)
| Field | Type | Nullable | Description |
|---|---|---|---|
ok | boolean | no | Whether your endpoint accepted it (a 2xx). |
status | integer or null | yes | Your endpoint's HTTP status; null when it could not be reached. |
latency_ms | integer | no | How long it took. |
at | string (date-time) | no | When it was sent. |
error | string or null | yes | Why it failed. |
message_id | string | no | The message recorded for it, in the log. |
Schemas
Detection
One agency item used in one publisher article, for one subscription. Without fields, a detection has every field its content type carries (the Content types column), event only on the change stream; a field the content type does not have is absent, not null, and an unknown value is null. With fields, only the fields asked for are present, and always id and version, so only those two are required.
| Field | Type | Nullable | Content types | Description |
|---|---|---|---|---|
id | string | no | text, image | <t|i>.<subscription>.<source internal id>.<article id>, e.g. t.9001.5000001.7000001. Stable forever; opaque to customers |
version | integer | no | text, image | 1 on first sight; +1 whenever a customer-visible field changes at least 1 |
event | string | no | text, image | created or updated. Present on the change stream only: /v1/detections and /v1/detections/{id} answer current states and leave it outone of created, updated |
content_type | string | no | text, image | text or imageone of text, image |
match_type | string | no | text, image | sentence_fingerprint for text, image_fingerprint for imagesone of sentence_fingerprint, image_fingerprint |
subscription_id | integer | no | text, image | The subscription the detection belongs to |
first_detected_at | string (date-time) | no | text, image | Ours: when the match first reached us. Backfilled rows are flagged (first_detected_estimated) |
first_detected_estimated | boolean | no | text, image | True when first_detected_at is estimated: a backfilled row |
last_scored_at | string (date-time) | no | text, image | The export's matched_at |
exported_at | string (date-time) | no | text, image | When EzyInsights wrote the row |
source | object | no | The agency's item. | |
source.id | string or null | yes | text, image | The agency's own id: a URN, a NewsML id, a UUID |
source.internal_id | integer | no | text, image | EzyInsights' id; links into the dashboard |
source.published_at | string (date-time) or null | yes | text, image | For images, the real publish time, not the record's creation |
source.language | string or null | yes | text | The wire story's language |
source.syndicated | boolean or null | yes | text | Whether the wire story is syndicated |
source.sentences | integer or null | yes | text | The wire story's sentence count, once exported |
source.headline | string or null | yes | text | The wire story's own headline, as supplied; null until the exports carry it. At most 1,000 characters (a longer one is cut). Not a versioned field: a change to it alone makes no new version and is not carried on the change stream; the detection's current state has it. Absent on text detections recorded before it was added, until they are next scored at most 1,000 characters |
source.image_url | string (uri) | no | image | Our signed proxy address of the agency's full-size photo. The signature is an HMAC of the path with no expiry: the link is permanent and works for anyone who has it; revoking it means rotating the signing key, which changes every link |
source.origin_url | string (uri) or null | yes | image | Where the agency's photo came from (imagewire_source_uri) |
strength | object | no | How strong the match is. | |
strength.score | number | no | text, image | Text: usage % (0–100); image: score (0–99) |
strength.band | string | no | text, image | Text off, low, medium, high, max; image low, medium, high. Lower-case in the API; legacy profiles map to the capitalised words. Thresholds per type: text as the export (25/50/75/95), image 30/60one of off, low, medium, high, max |
strength.matched_sentences | integer or null | yes | text | The export's estimate, in wire-story sentences |
strength.article_sentences | integer or null | yes | text | The publisher article's sentence count |
article | object | no | The publisher article the item was found in. | |
article.id | integer | no | text, image | The publisher article (content_story_id) |
article.url | string (uri) or null | yes | text, image | Canonical URL |
article.domain | string or null | yes | text, image | Registrable domain |
article.published_at | string (date-time) or null | yes | text, image | Unknown for 45% of text rows, 12% of image rows |
article.headline | string or null | yes | text, image | The publisher article's headline; null until the exports carry it |
article.publisher | object or null | yes | The publisher, or null when its id is unknown (the detection then carries the domain only). | |
article.publisher.id | integer | yes | text, image | The real publisher id |
article.publisher.name | string or null | yes | text, image | Trimmed |
article.print | boolean | no | text | Whether the publisher is a print title. For print articles, article.url is null outside the agencies licensed for NLA's metadata |
article.image_url | string (uri) or null | yes | image | The publisher's copy (matched_image_url) |
evidence | TextEvidenceEnvelope | no | How a text detection was matched, in brief: computed when the detection is answered or delivered, never stored, so gone is true from the moment expires_at is reached. As known when emitted on the change stream, webhooks and delivered files; expires_at is what a loader should read. Text detections only: image detections carry no evidence yet. | |
evidence.kind | string | no | Whose evidence this is; image evidence will come with kind image.always text | |
evidence.status | string | no | stored while the record is kept; missing for a print use (no page was collected, so nothing will exist); gone from expires_at on.one of stored, missing, gone | |
evidence.matched_at | string (date-time) | no | The match the detection stands on (its last_scored_at). | |
evidence.expires_at | string (date-time) | no | matched_at + 45 days: after it, the record is no longer kept. | |
evidence.article_text | string | no | What the record and the pack carry of the publisher's article: whole, or matched (the passages at similarity 0.65 and over; the rest counted, not shown).one of whole, matched | |
evidence.record | string (uri) | no | GET /v1/detections/{id}/evidence. | |
evidence.pack | string (uri) | no | GET /v1/detections/{id}/evidence/pack. | |
customer | boolean or null | yes | text, image | Whether the publisher is on the subscription's customer list; null until that list is exported |
classification | string or null | yes | text, image | licensed, potentially_unlicensed, unknown; null until classifiedone of licensed, potentially_unlicensed, unknown |
StreamCursor
A position in the change stream, opaque (base64url). Valid with any filter, never expires and survives a key roll.
Type: string.
QueryCursor
A position in one /v1/detections request, opaque (base64url). It carries a hash of the period, time zone, sort and filters, and is refused if they change.
Type: string.
Problem
Every error except the token endpoint's is an RFC 9457 problem document, sent as application/problem+json.
| Field | Type | Nullable | Description |
|---|---|---|---|
type | string (uri) | no | The kind of error. One of:
- https://api.ezyinsights.com/errors/invalid_request (400, Invalid request): a parameter, id or cursor is wrong; the detail says which.
- https://api.ezyinsights.com/errors/unauthorized (401, Unauthorized): no credential, or one that is malformed, unknown, expired or revoked.
- https://api.ezyinsights.com/errors/forbidden (403, Forbidden): a scope is missing, the address is not allowed or the API is suspended for the key's subscription.
- https://api.ezyinsights.com/errors/not_found (404, Not found): no endpoint at this path, or no such detection, used item, site, destination, webhook endpoint or message for this key.
- https://api.ezyinsights.com/errors/method_not_allowed (405, Method not allowed): the path does not answer this method; see Allow.
- https://api.ezyinsights.com/errors/content_too_large (413, Content too large): the token request's body is over 4 KiB, a Sites body over 5 MB or 20,000 rows, or a destination or webhook body over 64 KB.
- https://api.ezyinsights.com/errors/rate_limited (429, Too many requests): over a rate limit, or over 10 tests and replays an hour for a destination or webhook endpoint; see Retry-After.
- https://api.ezyinsights.com/errors/daily_allowance (429, Daily allowance used): the key or its subscription has used its daily row allowance; see Retry-After.
- https://api.ezyinsights.com/errors/internal (500, Internal error): our fault; retry with backoff.
- https://api.ezyinsights.com/errors/unavailable (503, Service unavailable): credentials cannot be verified right now, or our data store is restarting (Retry-After: 2); retry with backoff.
- https://api.ezyinsights.com/errors/limit_reached (409, Limit reached): a Sites list would be over its 10,000 sites (the detail says by how many), a subscription has 10 destinations or 10 webhook endpoints, or a destination's first delivery would be too large.
- https://api.ezyinsights.com/errors/state_conflict (409, Conflict): the change conflicts with the list as it is (rows overlapping listed sites without confirm_overlaps, a host and path already listed), or with a destination's or endpoint's state (a start before a passed test, a run while one runs, a change made meanwhile).
- https://api.ezyinsights.com/errors/precondition_failed (412, Precondition failed): the Sites list, destination or webhook endpoint changed since the If-Match version; the ETag is its version now.
- https://api.ezyinsights.com/errors/idempotency_key_reused (422, Unprocessable content): an Idempotency-Key used in the last 24 hours with a different request.
- https://api.ezyinsights.com/errors/evidence_gone (410, Evidence gone): a text detection's record of how it was matched is no longer kept (45 days after the match); expires_at says when it stopped.
- https://api.ezyinsights.com/errors/evidence_missing (404, Evidence missing): no record of how it was matched exists: a print use, or none found more than two hours after the match.
- https://api.ezyinsights.com/errors/evidence_not_available (404, Evidence not available): an image detection, whose evidence comes later.
- https://api.ezyinsights.com/errors/evidence_unavailable (503, Evidence unavailable): the record could not be read just now; retry with backoff. |
title | string | no | The type's title, as above. |
status | integer | no | The HTTP status. |
detail | string | no | What was wrong with this request, in plain English. |
request_id | string (uuid) | no | The request's id, the same as X-Request-Id. |
OAuthError
The token endpoint's errors (RFC 6749 §5.2).
| Field | Type | Nullable | Description |
|---|---|---|---|
error | string | no | one of invalid_request, invalid_client, unsupported_grant_type, invalid_scope |
error_description | string | no | What was wrong, in plain English. |