EzyInsights Detections API

Version 1.0.0 · Base URL https://api.ezyinsights.com

openapi.yaml · Changelog

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

  1. 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.

  2. Check it. GET /v1/me says 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"
    
  3. 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"
    
  4. Store next_cursor from every answer, together with the rows it brought, and pass it as cursor next time instead of since. While has_more is true, call again at once.

  5. Poll hourly with the stored cursor. When nothing is new you get an empty page and the same cursor back.

  6. Upsert by id, keeping the higher version. 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:

  1. Read the first page of GET /v1/detections for the most recent month and keep its as_of.
  2. Walk GET /v1/detections month by month back to data_starts (from GET /v1/me), following next_cursor until has_more is false in each month, and upsert every row by id, keeping the higher version.
  3. Start the change stream with since set to that first as_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_…

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" }

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.

How to read it:

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.

What you must know:

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"
}

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:

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.

Limits and allowances

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

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:

  1. POST …/sites/import with "dry_run": true answers the preview and the list's version.
  2. Check the preview: the sites to add, change or remove, the rows skipped and why, the overlaps.
  3. Send the same rows without dry_run, with If-Match: "<version>"; 412 means 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

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

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

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

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

Credentials

Every destination writes with one of two kinds of credential; a destination only ever needs to write objects under its prefix.

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 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:

  1. The article's publisher is known.
  2. The article is not dated before the wire story (an undated article is kept).
  3. The wire story has two or more sentences (an unknown count is kept).
  4. 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:

  1. The article's publisher is known.
  2. 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 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

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:

  1. Use the raw body, the bytes as received, before any JSON parsing: a body parsed and written again does not match.
  2. 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.
  3. Accept the message when any v1 signature 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:

  1. Create it: POST /v1/destinations. It starts in setting_up, and nothing is delivered yet.
  2. Set it up at your provider. For a federated destination (no secret stored: your cloud trusts our identity), GET /v1/destinations/{id}/setup answers the steps and policy text filled in with this destination's values, and the fields to send back; send them with PATCH /v1/destinations/{id} as federation. For stored credentials, send the credential with POST /v1/destinations/{id}/credential: it is written once to test it, and never shown again.
  3. Test the connection: POST /v1/destinations/{id}/test answers the provider's own words.
  4. 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:

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

NameInTypeRequiredDescription
cursorqueryStreamCursornoThe next_cursor of a previous answer from this endpoint. Exclusive with since. A value this endpoint did not give is 400.
sincequerystring (date-time)noStart 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.
limitqueryintegernoThe most rows to return.
1 to 1,000; default 100
subscription_idqueryintegernoOptional 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_typequerystringnoOnly this content type. It must be one the key can read; unset means every type in its scope.
one of text, image
publisher_idqueryarray of integernoOnly 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_idqueryarray of integernoEvery 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
domainqueryarray of stringnoOnly 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_domainqueryarray of stringnoEvery 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_bandquerystringnoOnly 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
bandqueryarray of stringnoExactly 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_scorequeryintegernoOnly 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
printquerybooleannotrue for print articles only, false for everything else. Image detections are never print.
source_idquerystringnoOnly detections of this agency item (source.id, the agency's own id), exactly as written.
at most 200 characters
article_idqueryintegernoOnly detections in this publisher article (article.id).
1 to 999,999,999,999,999
fieldsquerystringnoReturn 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_versionquerystringnoThe detection schema version. v1, the default, is the only one.
one of v1; default v1

Responses

StatusMeaningBodyHeaders
200A page of the stream.application/json: ChangesPageX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (ChangesPage)

FieldTypeNullableDescription
dataarray of DetectionnoThe detections, in the order they reached the API, each with event.
next_cursorStreamCursornoA position in the change stream, opaque (base64url). Valid with any filter, never expires and survives a key roll.
has_morebooleannoTrue to call again now with next_cursor; false when caught up (call again later with it).
as_ofstring (date-time) or nullyesThe 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

NameInTypeRequiredDescription
fromquerystringyesThe 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.
toquerystringyesThe 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_zonequerystringnoAn 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.
sortquerystringnoNewest 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
limitqueryintegernoThe 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
cursorqueryQueryCursornoThe 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_idqueryintegernoOptional 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_typequerystringnoOnly this content type. It must be one the key can read; unset means every type in its scope.
one of text, image
publisher_idqueryarray of integernoOnly 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_idqueryarray of integernoEvery 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
domainqueryarray of stringnoOnly 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_domainqueryarray of stringnoEvery 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_bandquerystringnoOnly 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
bandqueryarray of stringnoExactly 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_scorequeryintegernoOnly 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
printquerybooleannotrue for print articles only, false for everything else. Image detections are never print.
source_idquerystringnoOnly detections of this agency item (source.id, the agency's own id), exactly as written.
at most 200 characters
article_idqueryintegernoOnly detections in this publisher article (article.id).
1 to 999,999,999,999,999
fieldsquerystringnoReturn 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_versionquerystringnoThe detection schema version. v1, the default, is the only one.
one of v1; default v1

Responses

StatusMeaningBodyHeaders
200A page of the period.application/json: RangePageX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (RangePage)

FieldTypeNullableDescription
dataarray of DetectionnoThe detections' current states, in the requested sort, without event.
next_cursorQueryCursor or any or nullyesThe next page's cursor, or null when the period is read.
has_morebooleannoTrue when there may be another page (which can be empty).
fromstring (date-time)noThe period's start as resolved, inclusive.
tostring (date-time)noThe period's end as resolved, exclusive (now, if to was in the future).
time_zonestringnoThe time zone the period was read in.
as_ofstring (date-time) or nullyesAs 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

NameInTypeRequiredDescription
idpathstringyesThe 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})$
fieldsquerystringnoReturn 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_versionquerystringnoThe detection schema version. v1, the default, is the only one.
one of v1; default v1

Responses

StatusMeaningBodyHeaders
200The detection.application/json: DetectionX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-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

NameInTypeRequiredDescription
idpathstringyesThe 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

StatusMeaningBodyHeaders
200The record, or a use pending or suppressed.application/json: TextEvidenceAnswerX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
410evidence_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: EvidenceGoneProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503evidence_unavailable: the record could not be read just now; Retry-After when retrying can help. Or unavailable, as on every endpoint.application/problem+json: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (TextEvidenceAnswer)

FieldTypeNullableDescription
idstringnoThe detection's id.
evidenceTextEvidenceRecordnoThe 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.kindstringno
always text
evidence.statusstringnopending: 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_atstring (date-time)no
evidence.expires_atstring (date-time)no
evidence.article_textstringno
one of whole, matched
evidence.recordstring (uri)no
evidence.packstring (uri)no
evidence.useobjectnoThe use's own facts, from the detection.
evidence.use.publisher optionalobjectno
evidence.use.publisher.id optionalinteger or nullyes
evidence.use.publisher.name optionalstring or nullyes
evidence.use.article optionalobjectno
evidence.use.article.id optionalintegerno
evidence.use.article.url optionalstring or nullyes
evidence.use.article.domain optionalstring or nullyes
evidence.use.article.headline optionalstring or nullyes
evidence.use.article.published_at optionalstring (date-time) or nullyes
evidence.use.story optionalobjectno
evidence.use.story.id optionalintegerno
evidence.use.story.headline optionalstring or nullyes
evidence.use.story.published_at optionalstring (date-time) or nullyes
evidence.use.print optionalbooleanno
evidence.use.matched_at optionalstring (date-time)no
evidence.use.usage optionalnumber or nullyes
evidence.use.band optionalstring or nullyes
evidence.use.matched_sentences optionalinteger or nullyes
evidence.use.story_sentences optionalinteger or nullyes
evidence.use.article_sentences optionalinteger or nullyes
evidence.use.classification optionalstring or nullyes
evidence.matched optionalobjectnoEvery 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 optionalintegerno
evidence.matched.latest_at optionalstring (date-time)no
evidence.matched.first_at optionalstring (date-time)no
evidence.matched.first_usage optionalnumber or nullyes
evidence.matched.first_article_sentences optionalinteger or nullyes
evidence.matched.exact optionalbooleanno
evidence.recorded optionalobjectnoThe detection's own usage, as recorded.
evidence.recorded.usage optionalnumberno
evidence.recorded.at optionalstring (date-time)no
evidence.usage optionalobjectnoUsage 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 optionalintegerno
evidence.usage.at_80 optionalintegerno
evidence.usage.at_95 optionalintegerno
evidence.story optionalobjectnoYour story, the version the match saw.
evidence.story.id optionalintegerno
evidence.story.version_id optionalintegerno
evidence.story.version_number optionalintegerno
evidence.story.versions optionalintegerno
evidence.story.published_at optionalstring (date-time) or nullyes
evidence.story.is_newest optionalbooleanno
evidence.story.sentence_count optionalintegerno
evidence.story.sentences optionalarray of string or nullyesYour version's sentences as matched; null when that version was not kept (each pair then carries nearest_text).
evidence.story.paragraph_starts optionalarray of integer or nullyes
evidence.article optionalobjectnoThe publisher's article as collected for this match, a sentence an entry, in order.
evidence.article.id optionalintegerno
evidence.article.publisher optionalobject or nullyes
evidence.article.publisher.id optionalintegeryes
evidence.article.publisher.name optionalstring or nullyes
evidence.article.publisher.is_customer optionalboolean or nullyes
evidence.article.url optionalstring or nullyes
evidence.article.print optionalbooleanno
evidence.article.collected_at optionalstring (date-time)no
evidence.article.sentence_count optionalintegerno
evidence.article.paragraph_starts optionalarray of integer or nullyes
evidence.article.sentences optionalarray of objectno
evidence.article.sentences[].nintegernoTheir sentence's number.
evidence.article.sentences[].text optionalstringnoAbsent for a sentence under 0.65 when article_text is matched.
evidence.article.sentences[].nearestintegernoYour nearest sentence's number.
evidence.article.sentences[].similaritynumberno
0 to 1
evidence.article.sentences[].nearest_text optionalstringnoYour nearest sentence as quoted, only when story.sentences is null.
evidence.article.not_shown optionalobject or nullyesWhen sentences were left out (matched), how many and where.
evidence.article.not_shown.count optionalintegeryes
evidence.article.not_shown.runs optionalarray of objectyes
evidence.article.not_shown.runs[].from optionalintegerno
evidence.article.not_shown.runs[].to optionalintegerno

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

NameInTypeRequiredDescription
idpathstringyesThe 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

StatusMeaningBodyHeaders
200The 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
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
410evidence_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: EvidenceGoneProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503evidence_unavailable: the record could not be read just now; Retry-After when retrying can help. Or unavailable, as on every endpoint.application/problem+json: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body

FieldTypeNullableDescription

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

StatusMeaningBodyHeaders
200The key, its subscription and the limits.application/json: MeX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Me)

FieldTypeNullableDescription
keyobjectno
key.idstringnoThe key id (the 12 characters after ezy_live_).
key.namestringnoThe key's name.
key.scopesarray of stringnoThe scopes this credential has now (for a token, those it was issued with that the key still has).
key.expires_atstring (date-time) or nullyesWhen the key expires; null if it does not.
subscriptionobjectnoThe key's subscription, the only one it reads.
subscription.idintegernoThe subscription id, as detections carry it.
subscription.namestring or nullyesThe subscription's name.
subscription.content_typesarray of stringnoThe content types our exports carry for it; empty until they name it.
each one of text, image
subscription.time_zonestringnoThe subscription's IANA time zone, used for date-only periods.
subscription.data_startsobjectnoPer 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 optionalstring (date-time) or nullyes
subscription.data_starts.image optionalstring (date-time) or nullyes
subscription.customer_listsbooleannoWhether the subscription has a Sites list (GET /v1/subscriptions/{id}/sites), the list its detections' customer and classification come from.
subscription.classification_sincestring (date-time) or nullyesWhen 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 optionalobjectnoPresent 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 optionalstring (date-time) or nullyes
subscription.history_until.image optionalstring (date-time) or nullyes
subscription.rows_start optionalobjectnoPresent 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 optionalstring (date-time) or nullyes
subscription.rows_start.image optionalstring (date-time) or nullyes
data_gapsobjectnoPer 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 optionalarray of Gapno
data_gaps.text[].window_startstring (date-time)noThe start of the 10-minute export window.
data_gaps.text[].statusstringnomissing: 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 optionalarray of Gapno
data_gaps.image[].window_startstring (date-time)noThe start of the 10-minute export window.
data_gaps.image[].statusstringnomissing: 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
limitsobjectno
limits.requests_per_minuteintegernoRequests a minute per key.
limits.daily_rowsintegernoThe subscription's daily row allowance for detection reads.
limits.daily_file_rowsintegernoThe 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_dayintegernoExports the subscription may create a day (from a later version).
limits.throttledstring or nullyesWhether the key or the whole subscription is throttled by the daily row allowance.
one of key, subscription
limits.throttled_until optionalstring (date-time)noWhen the throttle ends (the next 00:00 UTC); present only while throttled.
schema_versionstringnoThe 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

NameInTypeRequiredDescription
schema_versionquerystringnoThe detection schema version. v1, the default, is the only one.
one of v1; default v1
If-None-MatchheaderstringnoAn ETag from an earlier answer (or a list of them, or *).

Responses

StatusMeaningBodyHeaders
200The schema.application/json: SchemaX-Request-Id, ETag, Cache-Control, RateLimit-Limit, RateLimit-Policy
304Not modified; If-None-Match named the current ETag. No body.noneX-Request-Id, ETag, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Schema)

FieldTypeNullableDescription
schema_versionstringno
one of v1
fieldsarray of SchemaFieldno
fields[].pathstringnoThe dotted path in the JSON detection.
fields[].columnstringnoThe flat column name for files; dots become underscores.
fields[].positionintegerno1-based position in the column list.
fields[].typestringnotimestamp is an ISO 8601 UTC time with whole seconds and Z.
one of string, integer, number, boolean, timestamp
fields[].nullablebooleanno
fields[].content_typesarray of stringnoThe content types that carry the field.
each one of text, image
fields[].descriptionstringno

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

NameInTypeRequiredDescription
schema_versionquerystringnoThe detection schema version. v1, the default, is the only one.
one of v1; default v1
If-None-MatchheaderstringnoAn ETag from an earlier answer (or a list of them, or *).

Responses

StatusMeaningBodyHeaders
200As GET, without the body.noneX-Request-Id, ETag, Cache-Control, RateLimit-Limit, RateLimit-Policy
304Not modified.noneX-Request-Id, ETag, Cache-Control, RateLimit-Limit, RateLimit-Policy
defaultAs 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:

FieldTypeRequiredDescription
grant_typestringyes
one of client_credentials
client_idstringnoThe key id. Omit when sending HTTP Basic credentials.
pattern ^[a-z2-7]{12}$
client_secretstringnoThe 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.
scopestringnoSpace-separated scopes, a subset of the key's. Omitted or empty: all of the key's scopes.

Responses

StatusMeaningBodyHeaders
200The access token.application/json: TokenX-Request-Id, Cache-Control, Pragma
400invalid_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: OAuthErrorX-Request-Id, Cache-Control, Pragma
401invalid_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: OAuthErrorX-Request-Id, Cache-Control, Pragma, WWW-Authenticate
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
413content_too_large: the body is larger than 4 KiB.application/problem+json: ProblemX-Request-Id, Cache-Control
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Token)

FieldTypeNullableDescription
access_tokenstringnoSend as Authorization: Bearer <access_token>.
token_typestringno
one of Bearer
expires_inintegernoSeconds the token lasts (3,600).
scopestringnoThe 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

StatusMeaningBodyHeaders
200Both exports are current.application/json: HealthX-Request-Id, Cache-Control
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503Degraded: 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: HealthX-Request-Id, Cache-Control

200 body (Health)

FieldTypeNullableDescription
statusstringno
one of ok, degraded
exportsobjectnoPer 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.newswireExportHealthno
exports.newswire.newest_donestring (date-time) or nullyesThe end of the newest finished window; null when there is none.
exports.imagewireExportHealthno
exports.imagewire.newest_donestring (date-time) or nullyesThe end of the newest finished window; null when there is none.
exports.subscription_customers optionalExportHealthno
exports.subscription_customers.newest_donestring (date-time) or nullyesThe end of the newest finished window; null when there is none.
exports.subscription_status optionalExportHealthno
exports.subscription_status.newest_donestring (date-time) or nullyesThe end of the newest finished window; null when there is none.
exports.publishers optionalExportHealthno
exports.publishers.newest_donestring (date-time) or nullyesThe end of the newest finished window; null when there is none.
exports.publisher_collection optionalExportHealthno
exports.publisher_collection.newest_donestring (date-time) or nullyesThe end of the newest finished window; null when there is none.
alertsobjectnoOur operational alerts, as counts only.
alerts.openintegernoAlerts open now.
at least 0
alerts.page_worthyintegernoOpen alerts that need someone now (ingest stalled, undeliverable ingest messages, API errors). Above 0, health is 503.
at least 0
alerts.pausedintegerno1 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

StatusMeaningBodyHeaders
200Both exports are current.noneX-Request-Id, Cache-Control
503Degraded.noneX-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

StatusMeaningBodyHeaders
200The discovery document.application/json: OpenIdConfigurationX-Request-Id, Cache-Control
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy

200 body (OpenIdConfiguration)

FieldTypeNullableDescription
issuerstringnoThe issuer, the iss of every identity token.
always https://api.ezyinsights.com
jwks_uristringnoWhere the public keys are.
always https://api.ezyinsights.com/oidc/jwks.json
response_types_supportedarray of stringno
each one of id_token
subject_types_supportedarray of stringno
each one of public
id_token_signing_alg_values_supportedarray of stringno
each one of ES256
claims_supportedarray of stringno
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

StatusMeaningBodyHeaders
200The discovery document exists.noneX-Request-Id, Cache-Control
404not_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: ProblemX-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

StatusMeaningBodyHeaders
200The key set.application/json: JsonWebKeySetX-Request-Id, Cache-Control
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy

200 body (JsonWebKeySet)

FieldTypeNullableDescription
keysarray of JsonWebKeyno
keys[].ktystringno
always EC
keys[].crvstringno
always P-256
keys[].xstringnoThe x coordinate, base64url.
keys[].ystringnoThe y coordinate, base64url.
keys[].usestringno
always sig
keys[].algstringno
always ES256
keys[].kidstringnoThe 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

StatusMeaningBodyHeaders
200The key set exists.noneX-Request-Id, Cache-Control
404not_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: ProblemX-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

NameInTypeRequiredDescription
content_typequerystringyestext (wire stories) or image (photos), in the key's scope.
one of text, image
published_fromquerystringnoWith 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_toquerystringnoThe period's end, exclusive; a date is the end of that day. A future value is read as now.
source_idquerystringnoThe 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_zonequerystringnoAn IANA time zone name for date-only bounds. Default: the subscription's own. Echoed as written.
sortquerystringnoWith 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
limitqueryintegernoThe most items to return, up to 500.
1 to 500; default 100
cursorqueryQueryCursornoThe next_cursor of the previous page of the same request.
subscription_idqueryintegernoOptional 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_versionquerystringnoThe detection schema version. v1, the default, is the only one.
one of v1; default v1

Responses

StatusMeaningBodyHeaders
200A page of items.application/json: SourcesPageX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (SourcesPage)

FieldTypeNullableDescription
dataarray of SourcenoThe items, in the selector's order.
data[].content_typestringno
one of text, image
data[].internal_idintegernoEzyInsights' id for the item (source.internal_id on its detections).
data[].subscription_idintegernoThe subscription these totals are for.
data[].source_idstring or nullyesThe agency's own id for the item (a URN, a UUID…), from its newest detection.
data[].published_atstring (date-time) or nullyesWhen the agency published the item, from its newest detection.
data[].headline optionalstring or nullyesText 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 optionalstring or nullyesImages only. Our signed proxy address of the agency's photo, as on its detections.
data[].detectionsintegernoHow many detections the item has.
data[].publishersintegernoHow many distinct publishers used it (publisher ids, or domains for detections without one).
data[].first_detected_atstring (date-time)noIts first use, the earliest first_detected_at of its detections.
data[].last_detected_atstring (date-time)noThe latest first_detected_at of its detections.
data[].best_scoreintegernoThe highest score of its detections, rounded.
data[].bandsobjectnoThe detections per band, strongest first; the content type's bands only (text max … off, image high … low).
data[].bands.max optionalintegerno
data[].bands.high optionalintegerno
data[].bands.medium optionalintegerno
data[].bands.low optionalintegerno
data[].bands.off optionalintegerno
next_cursorQueryCursor or any or nullyesThe next page's cursor, or null.
has_morebooleannoTrue when there may be another page (which can be empty).
from optionalstring (date-time)noWith a period selector, the period's start as resolved, inclusive.
to optionalstring (date-time)noWith a period selector, the period's end as resolved, exclusive.
time_zone optionalstringnoWith a period selector, the time zone it was read in.
as_ofstring (date-time) or nullyesAs 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

NameInTypeRequiredDescription
content_typepathstringyestext or image; anything else is 404.
one of text, image
internal_idpathintegeryesThe item's internal_id (source.internal_id on its detections); anything but a positive integer is 404.
at least 1
subscription_idqueryintegernoOptional 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

StatusMeaningBodyHeaders
200The item.application/json: SourceAnswerX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (SourceAnswer)

FieldTypeNullableDescription
content_typestringno
one of text, image
internal_idintegernoEzyInsights' id for the item (source.internal_id on its detections).
subscription_idintegernoThe subscription these totals are for.
source_idstring or nullyesThe agency's own id for the item (a URN, a UUID…), from its newest detection.
published_atstring (date-time) or nullyesWhen the agency published the item, from its newest detection.
headline optionalstring or nullyesText 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 optionalstring or nullyesImages only. Our signed proxy address of the agency's photo, as on its detections.
detectionsintegernoHow many detections the item has.
publishersintegernoHow many distinct publishers used it (publisher ids, or domains for detections without one).
first_detected_atstring (date-time)noIts first use, the earliest first_detected_at of its detections.
last_detected_atstring (date-time)noThe latest first_detected_at of its detections.
best_scoreintegernoThe highest score of its detections, rounded.
bandsSource/properties/bandsnoThe detections per band, strongest first; the content type's bands only (text max … off, image high … low).
bands.max optionalintegerno
bands.high optionalintegerno
bands.medium optionalintegerno
bands.low optionalintegerno
bands.off optionalintegerno
as_ofstring (date-time) or nullyesAs 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

NameInTypeRequiredDescription
content_typepathstringyestext or image; anything else is 404.
one of text, image
internal_idpathintegeryesThe item's internal_id (source.internal_id on its detections); anything but a positive integer is 404.
at least 1
sortquerystringnoNewest first, by score (highest first), or grouped by publisher id; ties by id.
one of -first_detected_at, -score, publisher; default -first_detected_at
limitqueryintegernoThe most rows to return, up to 1,000.
1 to 1,000; default 100
cursorqueryQueryCursornoThe next_cursor of the previous page of the same request.
subscription_idqueryintegernoOptional 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_typequerystringnoOnly this content type. It must be one the key can read; unset means every type in its scope.
one of text, image
publisher_idqueryarray of integernoOnly 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_idqueryarray of integernoEvery 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
domainqueryarray of stringnoOnly 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_domainqueryarray of stringnoEvery 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_bandquerystringnoOnly 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
bandqueryarray of stringnoExactly 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_scorequeryintegernoOnly 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
printquerybooleannotrue for print articles only, false for everything else. Image detections are never print.
article_idqueryintegernoOnly detections in this publisher article (article.id).
1 to 999,999,999,999,999
fieldsquerystringnoReturn 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_versionquerystringnoThe detection schema version. v1, the default, is the only one.
one of v1; default v1

Responses

StatusMeaningBodyHeaders
200A page of the item's uses.application/json: SourceDetectionsPageX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (SourceDetectionsPage)

FieldTypeNullableDescription
dataarray of DetectionnoThe item's detections' current states, in the requested sort, without event.
next_cursorQueryCursor or any or nullyesThe next page's cursor, or null.
has_morebooleannoTrue when the page is full (the next can be empty).
as_ofstring (date-time) or nullyesAs 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

NameInTypeRequiredDescription
fromquerystringyesThe period's start, inclusive: a date (that day's start in the time zone) or an ISO 8601 time.
toquerystringyesThe period's end, exclusive; a date is the end of that day. A future value is read as now.
time_zonequerystringnoThe IANA time zone days, weeks and months are counted in. Default: the subscription's own.
group_byqueryarray of stringnoRepeatable, 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
metricsqueryarray of stringnoRepeatable, or a comma-separated list. detections is always included.
each one of detections, publishers, new_sources
subscription_idqueryintegernoOptional 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_typequerystringnoOnly this content type. It must be one the key can read; unset means every type in its scope.
one of text, image
min_bandquerystringnoOnly 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
bandqueryarray of stringnoExactly 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_idqueryarray of integernoOnly 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
limitqueryintegernoGroups per page, up to 10,000.
1 to 10,000; default 1000
cursorqueryQueryCursornoThe next_cursor of the previous page: an offset with the request's hash, refused if the request changed.

Responses

StatusMeaningBodyHeaders
200A page of groups, with the period's totals.application/json: UsageReportX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (UsageReport)

FieldTypeNullableDescription
fromstring (date-time)noThe period's start as resolved, inclusive.
tostring (date-time)noThe period's end as resolved, exclusive (now, if to was in the future).
time_zonestringnoThe time zone buckets are counted in.
group_byarray of stringno
each one of hour, day, week, month, publisher, band, content_type
metricsarray of stringno
each one of detections, publishers, new_sources
dataarray of UsageGroupnoThis page's groups.
data[].hour optionalstringnoThe bucket's local start, YYYY-MM-DDTHH.
data[].day optionalstringnoThe local day, YYYY-MM-DD.
data[].week optionalstringnoThe ISO week, YYYY-Www (Monday start, in the time zone).
data[].month optionalstringnoThe local month, YYYY-MM.
data[].publisher optionalobject or nullyesThe publisher, or null for detections without a publisher id (then domain).
data[].publisher.id optionalintegeryes
data[].publisher.name optionalstring or nullyes
data[].domain optionalstring or nullyesWith publisher null, the detections' domain (null when unknown).
data[].band optionalstringno
one of off, low, medium, high, max
data[].content_type optionalstringno
one of text, image
data[].detectionsintegerno
data[].publishers optionalintegernoDistinct publishers; see publishers_summed.
data[].new_sources optionalintegernoItems used for the first time; at that publisher when grouped by publisher.
totalsobjectnoThe whole period, with the metrics asked for; new_sources counts each item once.
totals.detectionsintegerno
totals.publishers optionalintegerno
totals.new_sources optionalintegerno
next_cursorQueryCursor or any or nullyesThe next page's cursor, or null.
has_morebooleanno
as_ofstring (date-time) or nullyesAs on the change stream.
approximate_daysbooleannoTrue when a bucket boundary was moved to the nearest whole hour.
publishers_summedbooleannoTrue 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

NameInTypeRequiredDescription
idpathintegeryesThe key's subscription (/v1/me names it). Any other id is 404, whether it exists or not.
at least 1
qquerystringnoThe 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.
customerquerystringnoOnly customers (true) or only the others (false).
one of true, false
priorityquerystringnoOne priority.
one of high, normal, low
matchquerystringnoHow the site matches EzyInsights publishers: matched (one), several (more than one), unmatched (none).
one of matched, several, unmatched
healthquerystringnoThe 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_statusquerystringnoOne tracking status.
one of tracked, requested, being_added, cannot_track
problemsquerystringnoOnly 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
groupquerystringnoOne 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
limitqueryintegernoSites per page, 1 to 1,000.
1 to 1,000; default 100
cursorquerystringnoThe 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

StatusMeaningBodyHeaders
200One page of the list.application/json: SitesPageX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (SitesPage)

FieldTypeNullableDescription
dataarray of SitenoThe page, A to Z by host then path.
data[].idstringnoThe site's id; address it as …/sites/{id}.
pattern ^site_[0-9A-Z]{26}$
data[].subscription_idintegernoThe subscription whose list it is on.
data[].hoststringnoThe identity of the site with path: a registrable domain or a host under it, lower case, in punycode, without www..
data[].displaystringnoThe host in Unicode, for display (münchen.de for xn--mnchen-3ya.de).
data[].domainstringnoThe registrable domain of host, by the public suffix list the exporters use, as detections' article.domain has it.
data[].pathstringnoA path prefix that narrows the site; / for the whole host.
data[].namestring or nullyesThe name given in a list or by a change; null when none was.
data[].customerbooleannoThe agency licenses this site.
data[].prioritystringnoThe agency's own ranking.
one of high, normal, low
data[].publishersarray of objectnoThe EzyInsights publishers the site matches, by id (all of them when it matches several).
data[].publishers[].idintegernoThe publisher id, as detections' article.publisher.id has it.
data[].publishers[].namestring or nullyesThe publisher's name.
data[].publishers[].retiredbooleannoThe publisher is no longer collected; its old detections still match.
data[].matchstringnomatched: one publisher; several: more than one; unmatched: none.
one of matched, several, unmatched
data[].trackingobjectnoWhether EzyInsights collects the site. A new site without a matching publisher is requested; only EzyInsights staff move a request.
data[].tracking.statusstringnoThe tracking status.
one of tracked, requested, being_added, cannot_track
data[].tracking.sincestring (date-time)noWhen the status last changed.
data[].tracking.reasonstring or nullyesWhy it cannot be tracked; null otherwise.
one of paywall, blocks_collection, not_news, duplicate, other
data[].tracking.reason_textstring or nullyesMore about the reason, for this subscription; null when none.
data[].healthobject or nullyesHow well it is collected: the worst of its publishers'. Null when it matches no publisher or none has been measured yet.
data[].health.statusstringyesThe collection status.
one of healthy, degraded, not_collecting, unknown
data[].health.sincestring (date-time)yesWhen the status began.
data[].health.last_24hinteger or nullyesArticles collected in the last 24 hours.
data[].health.usual_dayinteger or nullyesArticles collected on a usual day.
data[].last_actionobject or nullyesThe newest action on the site or its publishers that this subscription may see.
data[].last_action.atstring (date-time)yesWhen.
data[].last_action.by_namestringyesWho (a person's name, a key's name, or EzyInsights).
data[].last_action.kindstringyesWhat kind of action.
one of note, tracking, health, import
data[].last_action.textstringyesWhat was done.
data[].sourceobjectnoHow the site was added.
data[].source.kindstringnoupload (a file), api (this API), app (the EzyInsights app), back_office (EzyInsights' earlier customer list).
one of upload, api, app, back_office
data[].source.filestring or nullyesThe file's name for an upload; else null.
data[].added_atstring (date-time)noWhen it was added.
data[].added_by_namestringnoWho added it.
data[].updated_atstring (date-time)noWhen it last changed.
data[].updated_by_namestringnoWho changed it last.
data[].versionintegernoThe site's own change counter, for information; If-Match takes the list's ETag.
data[].groupstring or nullyesThe agency's own group for the site, as given; null when it has none.
data[].pinnedbooleannotrue 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_idsarray of integernoThe publisher ids the site is pinned to; empty when it is matched by its address.
data[].labelsobjectnoUp to 5 columns kept from the agency's list, key to value.
next_cursorstring or nullyesSend as cursor for the next page; null on the last.
has_morebooleannoWhether another page follows.
countintegernoThe sites that match the filters, on every page.
collection_incidentobject or nullyesAn 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.sincestring (date-time)yesThe hour it began.
collection_incident.storiesintegeryesArticles collected in its last hour.
collection_incident.expectedintegeryesArticles expected in an hour.
health_checked_atstring (date-time) or nullyesWhen 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

NameInTypeRequiredDescription
idpathintegeryesThe key's subscription (/v1/me names it). Any other id is 404, whether it exists or not.
at least 1
If-MatchheaderstringnoThe 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:

FieldTypeRequiredDescription
idsarray of stringyes1 to 1,000 distinct site ids.
at most 1,000 values
customerbooleannoThe new customer for every site.
prioritystringnoThe new priority for every site.
one of high, normal, low
groupstring or nullnoThe 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

StatusMeaningBodyHeaders
200What changed; the ETag is the list's after the call.application/json: SitesPatchResultX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
413content_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (SitesPatchResult)

FieldTypeNullableDescription
changedintegernoSites changed.
unchangedintegernoSites that already had the values.
missingarray of stringnoIds 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

NameInTypeRequiredDescription
idpathintegeryesThe key's subscription (/v1/me names it). Any other id is 404, whether it exists or not.
at least 1
If-MatchheaderstringnoThe 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-KeyheaderstringnoAccepted and not stored in this version (see above).
listquerystringnotext/csv only, and then required: sites or customer.
one of sites, customer
modequerystringnotext/csv only, and then required: add or replace.
one of add, replace
default_priorityquerystringnotext/csv only: the priority of new sites whose row gives none.
one of high, normal, low; default normal
dry_runquerystringnotext/csv only: true answers the preview and writes nothing.
one of true, false
confirm_overlapsquerystringnotext/csv only: true keeps rows that overlap a listed site.
one of true, false

Request body

As application/json:

FieldTypeRequiredDescription
liststringyesA sites list, or a customer list (its sites are marked as customers).
one of sites, customer
modestringyesadd, or replace (also removes, or un-marks, what is not in the rows).
one of add, replace
default_prioritystringnoThe priority of new sites whose row gives none.
one of high, normal, low; default normal
rowsarray of objectyesThe sites, at most 20,000.
at most 20,000 values
dry_runbooleannotrue: answer the preview and write nothing.
confirm_overlapsbooleannotrue: keep rows that overlap a listed site.

As text/csv:

FieldTypeRequiredDescription

Responses

StatusMeaningBodyHeaders
200With 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 SitesImportResultX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
413content_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body

FieldTypeNullableDescription

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

NameInTypeRequiredDescription
idpathintegeryesThe key's subscription (/v1/me names it). Any other id is 404, whether it exists or not.
at least 1
sitepathstringyesA 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

StatusMeaningBodyHeaders
200The site.application/json: SiteWithActionsX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (SiteWithActions)

FieldTypeNullableDescription
idstringnoThe site's id; address it as …/sites/{id}.
pattern ^site_[0-9A-Z]{26}$
subscription_idintegernoThe subscription whose list it is on.
hoststringnoThe identity of the site with path: a registrable domain or a host under it, lower case, in punycode, without www..
displaystringnoThe host in Unicode, for display (münchen.de for xn--mnchen-3ya.de).
domainstringnoThe registrable domain of host, by the public suffix list the exporters use, as detections' article.domain has it.
pathstringnoA path prefix that narrows the site; / for the whole host.
namestring or nullyesThe name given in a list or by a change; null when none was.
customerbooleannoThe agency licenses this site.
prioritystringnoThe agency's own ranking.
one of high, normal, low
publishersarray of objectnoThe EzyInsights publishers the site matches, by id (all of them when it matches several).
publishers[].idintegernoThe publisher id, as detections' article.publisher.id has it.
publishers[].namestring or nullyesThe publisher's name.
publishers[].retiredbooleannoThe publisher is no longer collected; its old detections still match.
matchstringnomatched: one publisher; several: more than one; unmatched: none.
one of matched, several, unmatched
trackingobjectnoWhether EzyInsights collects the site. A new site without a matching publisher is requested; only EzyInsights staff move a request.
tracking.statusstringnoThe tracking status.
one of tracked, requested, being_added, cannot_track
tracking.sincestring (date-time)noWhen the status last changed.
tracking.reasonstring or nullyesWhy it cannot be tracked; null otherwise.
one of paywall, blocks_collection, not_news, duplicate, other
tracking.reason_textstring or nullyesMore about the reason, for this subscription; null when none.
healthobject or nullyesHow well it is collected: the worst of its publishers'. Null when it matches no publisher or none has been measured yet.
health.statusstringyesThe collection status.
one of healthy, degraded, not_collecting, unknown
health.sincestring (date-time)yesWhen the status began.
health.last_24hinteger or nullyesArticles collected in the last 24 hours.
health.usual_dayinteger or nullyesArticles collected on a usual day.
last_actionobject or nullyesThe newest action on the site or its publishers that this subscription may see.
last_action.atstring (date-time)yesWhen.
last_action.by_namestringyesWho (a person's name, a key's name, or EzyInsights).
last_action.kindstringyesWhat kind of action.
one of note, tracking, health, import
last_action.textstringyesWhat was done.
sourceobjectnoHow the site was added.
source.kindstringnoupload (a file), api (this API), app (the EzyInsights app), back_office (EzyInsights' earlier customer list).
one of upload, api, app, back_office
source.filestring or nullyesThe file's name for an upload; else null.
added_atstring (date-time)noWhen it was added.
added_by_namestringnoWho added it.
updated_atstring (date-time)noWhen it last changed.
updated_by_namestringnoWho changed it last.
versionintegernoThe site's own change counter, for information; If-Match takes the list's ETag.
groupstring or nullyesThe agency's own group for the site, as given; null when it has none.
pinnedbooleannotrue 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_idsarray of integernoThe publisher ids the site is pinned to; empty when it is matched by its address.
labelsobjectnoUp to 5 columns kept from the agency's list, key to value.
actionsarray of objectnoThe newest 20 actions on the site and its publishers that this subscription may see, newest first.
actions[].idstringnoThe action's id.
actions[].atstring (date-time)noWhen.
actions[].by_namestringnoWho.
actions[].kindstringnoWhat kind of action.
one of note, tracking, health, import
actions[].textstringnoWhat was done.
actions[].visibilitystringnosubscription: seen by this subscription; everyone: seen by every subscription that lists the publisher.
one of subscription, everyone
actions[].publisher_idinteger or nullyesThe 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

NameInTypeRequiredDescription
idpathintegeryesThe key's subscription (/v1/me names it). Any other id is 404, whether it exists or not.
at least 1
sitepathstringyesA 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-MatchheaderstringnoThe 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:

FieldTypeRequiredDescription
customerbooleannoThe agency licenses the site. On a create, false unless given.
prioritystringnoThe site's priority. On a create, normal unless given.
one of high, normal, low
namestring or nullnoA name for the site; null or empty removes it.
at most 200 characters
groupstring or nullnoThe agency's group for the site; null or empty removes it.
at most 80 characters
labelsobjectnoThe site's labels, replacing its own; keys up to 40 characters.
publisher_idsarray of integernoPins 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
pinnedbooleannofalse matches a pinned site by its address again, at once. Not with publisher_ids.
always false

Responses

StatusMeaningBodyHeaders
200Changed, or already so.application/json: SiteX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
201Created.application/json: SiteX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
413content_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Site)

FieldTypeNullableDescription
idstringnoThe site's id; address it as …/sites/{id}.
pattern ^site_[0-9A-Z]{26}$
subscription_idintegernoThe subscription whose list it is on.
hoststringnoThe identity of the site with path: a registrable domain or a host under it, lower case, in punycode, without www..
displaystringnoThe host in Unicode, for display (münchen.de for xn--mnchen-3ya.de).
domainstringnoThe registrable domain of host, by the public suffix list the exporters use, as detections' article.domain has it.
pathstringnoA path prefix that narrows the site; / for the whole host.
namestring or nullyesThe name given in a list or by a change; null when none was.
customerbooleannoThe agency licenses this site.
prioritystringnoThe agency's own ranking.
one of high, normal, low
publishersarray of objectnoThe EzyInsights publishers the site matches, by id (all of them when it matches several).
publishers[].idintegernoThe publisher id, as detections' article.publisher.id has it.
publishers[].namestring or nullyesThe publisher's name.
publishers[].retiredbooleannoThe publisher is no longer collected; its old detections still match.
matchstringnomatched: one publisher; several: more than one; unmatched: none.
one of matched, several, unmatched
trackingobjectnoWhether EzyInsights collects the site. A new site without a matching publisher is requested; only EzyInsights staff move a request.
tracking.statusstringnoThe tracking status.
one of tracked, requested, being_added, cannot_track
tracking.sincestring (date-time)noWhen the status last changed.
tracking.reasonstring or nullyesWhy it cannot be tracked; null otherwise.
one of paywall, blocks_collection, not_news, duplicate, other
tracking.reason_textstring or nullyesMore about the reason, for this subscription; null when none.
healthobject or nullyesHow well it is collected: the worst of its publishers'. Null when it matches no publisher or none has been measured yet.
health.statusstringyesThe collection status.
one of healthy, degraded, not_collecting, unknown
health.sincestring (date-time)yesWhen the status began.
health.last_24hinteger or nullyesArticles collected in the last 24 hours.
health.usual_dayinteger or nullyesArticles collected on a usual day.
last_actionobject or nullyesThe newest action on the site or its publishers that this subscription may see.
last_action.atstring (date-time)yesWhen.
last_action.by_namestringyesWho (a person's name, a key's name, or EzyInsights).
last_action.kindstringyesWhat kind of action.
one of note, tracking, health, import
last_action.textstringyesWhat was done.
sourceobjectnoHow the site was added.
source.kindstringnoupload (a file), api (this API), app (the EzyInsights app), back_office (EzyInsights' earlier customer list).
one of upload, api, app, back_office
source.filestring or nullyesThe file's name for an upload; else null.
added_atstring (date-time)noWhen it was added.
added_by_namestringnoWho added it.
updated_atstring (date-time)noWhen it last changed.
updated_by_namestringnoWho changed it last.
versionintegernoThe site's own change counter, for information; If-Match takes the list's ETag.
groupstring or nullyesThe agency's own group for the site, as given; null when it has none.
pinnedbooleannotrue 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_idsarray of integernoThe publisher ids the site is pinned to; empty when it is matched by its address.
labelsobjectnoUp to 5 columns kept from the agency's list, key to value.

201 body (Site)

FieldTypeNullableDescription
idstringnoThe site's id; address it as …/sites/{id}.
pattern ^site_[0-9A-Z]{26}$
subscription_idintegernoThe subscription whose list it is on.
hoststringnoThe identity of the site with path: a registrable domain or a host under it, lower case, in punycode, without www..
displaystringnoThe host in Unicode, for display (münchen.de for xn--mnchen-3ya.de).
domainstringnoThe registrable domain of host, by the public suffix list the exporters use, as detections' article.domain has it.
pathstringnoA path prefix that narrows the site; / for the whole host.
namestring or nullyesThe name given in a list or by a change; null when none was.
customerbooleannoThe agency licenses this site.
prioritystringnoThe agency's own ranking.
one of high, normal, low
publishersarray of objectnoThe EzyInsights publishers the site matches, by id (all of them when it matches several).
publishers[].idintegernoThe publisher id, as detections' article.publisher.id has it.
publishers[].namestring or nullyesThe publisher's name.
publishers[].retiredbooleannoThe publisher is no longer collected; its old detections still match.
matchstringnomatched: one publisher; several: more than one; unmatched: none.
one of matched, several, unmatched
trackingobjectnoWhether EzyInsights collects the site. A new site without a matching publisher is requested; only EzyInsights staff move a request.
tracking.statusstringnoThe tracking status.
one of tracked, requested, being_added, cannot_track
tracking.sincestring (date-time)noWhen the status last changed.
tracking.reasonstring or nullyesWhy it cannot be tracked; null otherwise.
one of paywall, blocks_collection, not_news, duplicate, other
tracking.reason_textstring or nullyesMore about the reason, for this subscription; null when none.
healthobject or nullyesHow well it is collected: the worst of its publishers'. Null when it matches no publisher or none has been measured yet.
health.statusstringyesThe collection status.
one of healthy, degraded, not_collecting, unknown
health.sincestring (date-time)yesWhen the status began.
health.last_24hinteger or nullyesArticles collected in the last 24 hours.
health.usual_dayinteger or nullyesArticles collected on a usual day.
last_actionobject or nullyesThe newest action on the site or its publishers that this subscription may see.
last_action.atstring (date-time)yesWhen.
last_action.by_namestringyesWho (a person's name, a key's name, or EzyInsights).
last_action.kindstringyesWhat kind of action.
one of note, tracking, health, import
last_action.textstringyesWhat was done.
sourceobjectnoHow the site was added.
source.kindstringnoupload (a file), api (this API), app (the EzyInsights app), back_office (EzyInsights' earlier customer list).
one of upload, api, app, back_office
source.filestring or nullyesThe file's name for an upload; else null.
added_atstring (date-time)noWhen it was added.
added_by_namestringnoWho added it.
updated_atstring (date-time)noWhen it last changed.
updated_by_namestringnoWho changed it last.
versionintegernoThe site's own change counter, for information; If-Match takes the list's ETag.
groupstring or nullyesThe agency's own group for the site, as given; null when it has none.
pinnedbooleannotrue 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_idsarray of integernoThe publisher ids the site is pinned to; empty when it is matched by its address.
labelsobjectnoUp 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

NameInTypeRequiredDescription
idpathintegeryesThe key's subscription (/v1/me names it). Any other id is 404, whether it exists or not.
at least 1
sitepathstringyesA 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-MatchheaderstringnoThe 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

StatusMeaningBodyHeaders
204Removed, or not there.noneX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-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

StatusMeaningBodyHeaders
200The destinations.application/json: DestinationsPageX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (DestinationsPage)

FieldTypeNullableDescription
dataarray of DestinationnoThe destinations, newest first.
data[].idstringnoThe destination's id (dst_…).
data[].namestringnoIts name, 1 to 60 characters.
data[].providerstringnoThe storage provider.
one of s3, s3_compatible, gcs, azure
data[].bucketstringnoThe bucket (or Azure container).
data[].prefixstringnoThe key prefix files are written under; empty or ending in /.
data[].regionstring or nullyesThe region, where the provider has one.
data[].endpointstring or nullyesAn S3-compatible store's address.
data[].storage_accountstring or nullyesAzure's storage account.
data[].auth_modestringnofederated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.
one of federated, stored
data[].federationobject or object or object or any or nullyesA federated destination's values, null until they are sent.
data[].formatstringnoThe file format.
one of jsonl, csv, tsv, json, parquet, avro
data[].compressionstringnoThe files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.
one of gzip, zstd, none
data[].format_optionsFormatOptionsnoCSV'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 optionalstringno, or ; for CSV; a tab for TSV.
one of ,, ;,
data[].format_options.header optionalbooleannoA header row first.
default true
data[].format_options.bom optionalbooleannoA UTF-8 byte order mark first, for spreadsheets.
default false
data[].format_options.evidence_text optionalbooleannoMatched 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_versionstringnoThe detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).
one of v1, legacy
data[].columnsarray of string or nullyesThe 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[].filterPushFilternoWhich detections a destination delivers; every field optional, all given must hold.
data[].filter.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
data[].filter.min_band optionalstringnoThe weakest strength delivered; max means text only reaches it.
one of off, low, medium, high, max
data[].filter.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
data[].filter.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
data[].scheduleobject or object or objectnoWhen a destination delivers.
data[].next_run_atstring (date-time) or nullyesThe next scheduled delivery; null while none is scheduled (setting up, paused).
data[].start_atstring (date-time)noWhere the first delivery started.
data[].cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
data[].cursor.seqintegernoThe chunk's sequence number.
data[].cursor.rowintegernoRows of that chunk read.
data[].delivered_up_tostring (date-time) or nullyesWhen the newest done delivery finished; null before the first.
data[].statusstringnosetting_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_atstring (date-time) or nullyesThe last connection test.
data[].last_test_okboolean or nullyesWhether it passed.
data[].last_test_errorstring or nullyesThe provider's words when it failed.
data[].running_sincestring (date-time) or nullyesWhen the delivery running now started.
data[].failing_sincestring (date-time) or nullyesWhen it began failing.
data[].versionintegernoIts configuration's version, also the ETag.
data[].created_atstring (date-time)noWhen it was created.
data[].created_by_namestringnoWho created it (a person or a key's name).
data[].updated_atstring (date-time)noIts last change.
data[].credentialCredential or any or nullyesThe active credential, else the pending one, else null (always null for a federated destination).
data[].last_deliveryDelivery or any or nullyesThe newest delivery, or null.
data[].test_prefixstring or nullyesA 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_cursorany or nullyesAlways null (one page).
has_morebooleannoAlways 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

NameInTypeRequiredDescription
Idempotency-Keyheaderstringno1 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:

FieldTypeRequiredDescription
namestringyesIts name.
at most 60 characters
providerstringyesThe storage provider; only those available now are accepted.
one of s3, s3_compatible, gcs, azure
bucketstringyesThe bucket (or Azure container).
prefixstringnoA key prefix, without ..; a trailing / is added.
at most 512 characters
regionstringnoThe region; required for S3.
endpointstringnoAn S3-compatible store's public https address; only for s3_compatible.
storage_accountstringnoAzure's storage account; only for azure.
auth_modestringyesfederated (Amazon S3 and Google Cloud Storage) or stored.
one of federated, stored
formatstringyesThe file format; only those available now are accepted.
one of jsonl, csv, tsv, json, parquet, avro
compressionstringyesThe 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_optionsFormatOptionsnoCSV'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.
columnsarray of string or nullnoThe 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.
filterPushFilternoWhich detections a destination delivers; every field optional, all given must hold.
scheduleobject or object or objectyesWhen a destination delivers.
startstringyesWhere 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

StatusMeaningBodyHeaders
201Created, 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: DestinationX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag, Idempotent-Replayed
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
413content_too_large: the body is larger than 64 KB (65,536 bytes).application/problem+json: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
422idempotency_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
429rate_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

201 body (Destination)

FieldTypeNullableDescription
idstringnoThe destination's id (dst_…).
namestringnoIts name, 1 to 60 characters.
providerstringnoThe storage provider.
one of s3, s3_compatible, gcs, azure
bucketstringnoThe bucket (or Azure container).
prefixstringnoThe key prefix files are written under; empty or ending in /.
regionstring or nullyesThe region, where the provider has one.
endpointstring or nullyesAn S3-compatible store's address.
storage_accountstring or nullyesAzure's storage account.
auth_modestringnofederated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.
one of federated, stored
federationobject or object or object or any or nullyesA federated destination's values, null until they are sent.
formatstringnoThe file format.
one of jsonl, csv, tsv, json, parquet, avro
compressionstringnoThe files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.
one of gzip, zstd, none
format_optionsFormatOptionsnoCSV'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 optionalstringno, or ; for CSV; a tab for TSV.
one of ,, ;,
format_options.header optionalbooleannoA header row first.
default true
format_options.bom optionalbooleannoA UTF-8 byte order mark first, for spreadsheets.
default false
format_options.evidence_text optionalbooleannoMatched 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_versionstringnoThe detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).
one of v1, legacy
columnsarray of string or nullyesThe 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).
filterPushFilternoWhich detections a destination delivers; every field optional, all given must hold.
filter.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
filter.min_band optionalstringnoThe weakest strength delivered; max means text only reaches it.
one of off, low, medium, high, max
filter.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
filter.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
scheduleobject or object or objectnoWhen a destination delivers.
next_run_atstring (date-time) or nullyesThe next scheduled delivery; null while none is scheduled (setting up, paused).
start_atstring (date-time)noWhere the first delivery started.
cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
cursor.seqintegernoThe chunk's sequence number.
cursor.rowintegernoRows of that chunk read.
delivered_up_tostring (date-time) or nullyesWhen the newest done delivery finished; null before the first.
statusstringnosetting_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_atstring (date-time) or nullyesThe last connection test.
last_test_okboolean or nullyesWhether it passed.
last_test_errorstring or nullyesThe provider's words when it failed.
running_sincestring (date-time) or nullyesWhen the delivery running now started.
failing_sincestring (date-time) or nullyesWhen it began failing.
versionintegernoIts configuration's version, also the ETag.
created_atstring (date-time)noWhen it was created.
created_by_namestringnoWho created it (a person or a key's name).
updated_atstring (date-time)noIts last change.
credentialCredential or any or nullyesThe active credential, else the pending one, else null (always null for a federated destination).
last_deliveryDelivery or any or nullyesThe newest delivery, or null.
test_prefixstring or nullyesA 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

NameInTypeRequiredDescription
idpathstringyesA destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.

Responses

StatusMeaningBodyHeaders
200The destination.application/json: DestinationX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Destination)

FieldTypeNullableDescription
idstringnoThe destination's id (dst_…).
namestringnoIts name, 1 to 60 characters.
providerstringnoThe storage provider.
one of s3, s3_compatible, gcs, azure
bucketstringnoThe bucket (or Azure container).
prefixstringnoThe key prefix files are written under; empty or ending in /.
regionstring or nullyesThe region, where the provider has one.
endpointstring or nullyesAn S3-compatible store's address.
storage_accountstring or nullyesAzure's storage account.
auth_modestringnofederated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.
one of federated, stored
federationobject or object or object or any or nullyesA federated destination's values, null until they are sent.
formatstringnoThe file format.
one of jsonl, csv, tsv, json, parquet, avro
compressionstringnoThe files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.
one of gzip, zstd, none
format_optionsFormatOptionsnoCSV'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 optionalstringno, or ; for CSV; a tab for TSV.
one of ,, ;,
format_options.header optionalbooleannoA header row first.
default true
format_options.bom optionalbooleannoA UTF-8 byte order mark first, for spreadsheets.
default false
format_options.evidence_text optionalbooleannoMatched 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_versionstringnoThe detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).
one of v1, legacy
columnsarray of string or nullyesThe 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).
filterPushFilternoWhich detections a destination delivers; every field optional, all given must hold.
filter.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
filter.min_band optionalstringnoThe weakest strength delivered; max means text only reaches it.
one of off, low, medium, high, max
filter.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
filter.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
scheduleobject or object or objectnoWhen a destination delivers.
next_run_atstring (date-time) or nullyesThe next scheduled delivery; null while none is scheduled (setting up, paused).
start_atstring (date-time)noWhere the first delivery started.
cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
cursor.seqintegernoThe chunk's sequence number.
cursor.rowintegernoRows of that chunk read.
delivered_up_tostring (date-time) or nullyesWhen the newest done delivery finished; null before the first.
statusstringnosetting_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_atstring (date-time) or nullyesThe last connection test.
last_test_okboolean or nullyesWhether it passed.
last_test_errorstring or nullyesThe provider's words when it failed.
running_sincestring (date-time) or nullyesWhen the delivery running now started.
failing_sincestring (date-time) or nullyesWhen it began failing.
versionintegernoIts configuration's version, also the ETag.
created_atstring (date-time)noWhen it was created.
created_by_namestringnoWho created it (a person or a key's name).
updated_atstring (date-time)noIts last change.
credentialCredential or any or nullyesThe active credential, else the pending one, else null (always null for a federated destination).
last_deliveryDelivery or any or nullyesThe newest delivery, or null.
test_prefixstring or nullyesA 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

NameInTypeRequiredDescription
idpathstringyesA destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
If-MatchheaderstringnoThe 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:

FieldTypeRequiredDescription
namestringnoIts name.
at most 60 characters
scheduleobject or object or objectnoWhen a destination delivers.
formatstringnoThe file format.
one of jsonl, csv, tsv, json, parquet, avro
compressionstringnoThe 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_optionsFormatOptionsnoCSV'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.
columnsarray of string or nullnoThe 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.
filterPushFilternoWhich detections a destination delivers; every field optional, all given must hold.
federationobject or object or objectnoA federated destination's values, from its setup steps; exactly its provider's fields.

Responses

StatusMeaningBodyHeaders
200Changed, or already so.application/json: DestinationX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
413content_too_large: the body is larger than 64 KB (65,536 bytes).application/problem+json: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Destination)

FieldTypeNullableDescription
idstringnoThe destination's id (dst_…).
namestringnoIts name, 1 to 60 characters.
providerstringnoThe storage provider.
one of s3, s3_compatible, gcs, azure
bucketstringnoThe bucket (or Azure container).
prefixstringnoThe key prefix files are written under; empty or ending in /.
regionstring or nullyesThe region, where the provider has one.
endpointstring or nullyesAn S3-compatible store's address.
storage_accountstring or nullyesAzure's storage account.
auth_modestringnofederated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.
one of federated, stored
federationobject or object or object or any or nullyesA federated destination's values, null until they are sent.
formatstringnoThe file format.
one of jsonl, csv, tsv, json, parquet, avro
compressionstringnoThe files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.
one of gzip, zstd, none
format_optionsFormatOptionsnoCSV'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 optionalstringno, or ; for CSV; a tab for TSV.
one of ,, ;,
format_options.header optionalbooleannoA header row first.
default true
format_options.bom optionalbooleannoA UTF-8 byte order mark first, for spreadsheets.
default false
format_options.evidence_text optionalbooleannoMatched 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_versionstringnoThe detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).
one of v1, legacy
columnsarray of string or nullyesThe 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).
filterPushFilternoWhich detections a destination delivers; every field optional, all given must hold.
filter.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
filter.min_band optionalstringnoThe weakest strength delivered; max means text only reaches it.
one of off, low, medium, high, max
filter.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
filter.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
scheduleobject or object or objectnoWhen a destination delivers.
next_run_atstring (date-time) or nullyesThe next scheduled delivery; null while none is scheduled (setting up, paused).
start_atstring (date-time)noWhere the first delivery started.
cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
cursor.seqintegernoThe chunk's sequence number.
cursor.rowintegernoRows of that chunk read.
delivered_up_tostring (date-time) or nullyesWhen the newest done delivery finished; null before the first.
statusstringnosetting_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_atstring (date-time) or nullyesThe last connection test.
last_test_okboolean or nullyesWhether it passed.
last_test_errorstring or nullyesThe provider's words when it failed.
running_sincestring (date-time) or nullyesWhen the delivery running now started.
failing_sincestring (date-time) or nullyesWhen it began failing.
versionintegernoIts configuration's version, also the ETag.
created_atstring (date-time)noWhen it was created.
created_by_namestringnoWho created it (a person or a key's name).
updated_atstring (date-time)noIts last change.
credentialCredential or any or nullyesThe active credential, else the pending one, else null (always null for a federated destination).
last_deliveryDelivery or any or nullyesThe newest delivery, or null.
test_prefixstring or nullyesA 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

NameInTypeRequiredDescription
idpathstringyesA destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
If-MatchheaderstringnoThe 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

StatusMeaningBodyHeaders
204Deleted. The ETag is its last version.noneX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-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

NameInTypeRequiredDescription
idpathstringyesA destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.

Responses

StatusMeaningBodyHeaders
200The steps and the fields.application/json: SetupStepsX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (SetupSteps)

FieldTypeNullableDescription
stepsarray of objectnoThe steps, in order.
steps[].textstringnoWhat to do.
steps[].code optionalstringnoA command or policy to paste, filled in with this destination's values.
steps[].copy_label optionalstringnoA label for the code.
fieldsarray of objectnoThe values to send with PATCH as federation.
fields[].namestringnoThe field's name in federation.
fields[].labelstringnoIts label.
fields[].placeholderstringnoAn example value.
fields[].patternstringnoThe 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

NameInTypeRequiredDescription
idpathstringyesA destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
If-MatchheaderstringnoThe 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-Keyheaderstringno1 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:

FieldTypeRequiredDescription

Responses

StatusMeaningBodyHeaders
200The test, the credential now (never a value) and the destination.application/json: CredentialReplacedX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag, Idempotent-Replayed
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
413content_too_large: the body is larger than 64 KB (65,536 bytes).application/problem+json: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
422idempotency_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
429rate_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (CredentialReplaced)

FieldTypeNullableDescription
testTestResult or any or nullyesThe test write; null on a repeated Idempotency-Key (a test is answered once).
credentialCredential or any or nullyesThe active credential now (the new one when its test passed), else null.
destinationDestinationnoA destination, never a secret.
destination.idstringnoThe destination's id (dst_…).
destination.namestringnoIts name, 1 to 60 characters.
destination.providerstringnoThe storage provider.
one of s3, s3_compatible, gcs, azure
destination.bucketstringnoThe bucket (or Azure container).
destination.prefixstringnoThe key prefix files are written under; empty or ending in /.
destination.regionstring or nullyesThe region, where the provider has one.
destination.endpointstring or nullyesAn S3-compatible store's address.
destination.storage_accountstring or nullyesAzure's storage account.
destination.auth_modestringnofederated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.
one of federated, stored
destination.federationobject or object or object or any or nullyesA federated destination's values, null until they are sent.
destination.formatstringnoThe file format.
one of jsonl, csv, tsv, json, parquet, avro
destination.compressionstringnoThe files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.
one of gzip, zstd, none
destination.format_optionsFormatOptionsnoCSV'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 optionalstringno, or ; for CSV; a tab for TSV.
one of ,, ;,
destination.format_options.header optionalbooleannoA header row first.
default true
destination.format_options.bom optionalbooleannoA UTF-8 byte order mark first, for spreadsheets.
default false
destination.format_options.evidence_text optionalbooleannoMatched 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_versionstringnoThe detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).
one of v1, legacy
destination.columnsarray of string or nullyesThe 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.filterPushFilternoWhich detections a destination delivers; every field optional, all given must hold.
destination.filter.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
destination.filter.min_band optionalstringnoThe weakest strength delivered; max means text only reaches it.
one of off, low, medium, high, max
destination.filter.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
destination.filter.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
destination.scheduleobject or object or objectnoWhen a destination delivers.
destination.next_run_atstring (date-time) or nullyesThe next scheduled delivery; null while none is scheduled (setting up, paused).
destination.start_atstring (date-time)noWhere the first delivery started.
destination.cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
destination.cursor.seqintegernoThe chunk's sequence number.
destination.cursor.rowintegernoRows of that chunk read.
destination.delivered_up_tostring (date-time) or nullyesWhen the newest done delivery finished; null before the first.
destination.statusstringnosetting_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_atstring (date-time) or nullyesThe last connection test.
destination.last_test_okboolean or nullyesWhether it passed.
destination.last_test_errorstring or nullyesThe provider's words when it failed.
destination.running_sincestring (date-time) or nullyesWhen the delivery running now started.
destination.failing_sincestring (date-time) or nullyesWhen it began failing.
destination.versionintegernoIts configuration's version, also the ETag.
destination.created_atstring (date-time)noWhen it was created.
destination.created_by_namestringnoWho created it (a person or a key's name).
destination.updated_atstring (date-time)noIts last change.
destination.credentialCredential or any or nullyesThe active credential, else the pending one, else null (always null for a federated destination).
destination.last_deliveryDelivery or any or nullyesThe newest delivery, or null.
destination.test_prefixstring or nullyesA 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

NameInTypeRequiredDescription
idpathstringyesA destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
If-MatchheaderstringnoThe 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

StatusMeaningBodyHeaders
200The attempt.application/json: TestResultX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
429rate_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (TestResult)

FieldTypeNullableDescription
okbooleannoWhether the write succeeded.
statusinteger or nullyesThe provider's HTTP status; null when it could not be reached.
codestring or nullyesThe provider's error code.
messagestring or nullyesThe provider's error message.
atstring (date-time)noWhen it was made.
keystring or nullyesThe key written (<prefix>_ezyinsights_test.json), when it succeeded.
latency_msintegernoHow 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

NameInTypeRequiredDescription
idpathstringyesA destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
If-MatchheaderstringnoThe 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

StatusMeaningBodyHeaders
200The destination now.application/json: DestinationX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Destination)

FieldTypeNullableDescription
idstringnoThe destination's id (dst_…).
namestringnoIts name, 1 to 60 characters.
providerstringnoThe storage provider.
one of s3, s3_compatible, gcs, azure
bucketstringnoThe bucket (or Azure container).
prefixstringnoThe key prefix files are written under; empty or ending in /.
regionstring or nullyesThe region, where the provider has one.
endpointstring or nullyesAn S3-compatible store's address.
storage_accountstring or nullyesAzure's storage account.
auth_modestringnofederated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.
one of federated, stored
federationobject or object or object or any or nullyesA federated destination's values, null until they are sent.
formatstringnoThe file format.
one of jsonl, csv, tsv, json, parquet, avro
compressionstringnoThe files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.
one of gzip, zstd, none
format_optionsFormatOptionsnoCSV'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 optionalstringno, or ; for CSV; a tab for TSV.
one of ,, ;,
format_options.header optionalbooleannoA header row first.
default true
format_options.bom optionalbooleannoA UTF-8 byte order mark first, for spreadsheets.
default false
format_options.evidence_text optionalbooleannoMatched 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_versionstringnoThe detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).
one of v1, legacy
columnsarray of string or nullyesThe 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).
filterPushFilternoWhich detections a destination delivers; every field optional, all given must hold.
filter.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
filter.min_band optionalstringnoThe weakest strength delivered; max means text only reaches it.
one of off, low, medium, high, max
filter.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
filter.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
scheduleobject or object or objectnoWhen a destination delivers.
next_run_atstring (date-time) or nullyesThe next scheduled delivery; null while none is scheduled (setting up, paused).
start_atstring (date-time)noWhere the first delivery started.
cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
cursor.seqintegernoThe chunk's sequence number.
cursor.rowintegernoRows of that chunk read.
delivered_up_tostring (date-time) or nullyesWhen the newest done delivery finished; null before the first.
statusstringnosetting_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_atstring (date-time) or nullyesThe last connection test.
last_test_okboolean or nullyesWhether it passed.
last_test_errorstring or nullyesThe provider's words when it failed.
running_sincestring (date-time) or nullyesWhen the delivery running now started.
failing_sincestring (date-time) or nullyesWhen it began failing.
versionintegernoIts configuration's version, also the ETag.
created_atstring (date-time)noWhen it was created.
created_by_namestringnoWho created it (a person or a key's name).
updated_atstring (date-time)noIts last change.
credentialCredential or any or nullyesThe active credential, else the pending one, else null (always null for a federated destination).
last_deliveryDelivery or any or nullyesThe newest delivery, or null.
test_prefixstring or nullyesA 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

NameInTypeRequiredDescription
idpathstringyesA destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
If-MatchheaderstringnoThe 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

StatusMeaningBodyHeaders
200The destination now.application/json: DestinationX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Destination)

FieldTypeNullableDescription
idstringnoThe destination's id (dst_…).
namestringnoIts name, 1 to 60 characters.
providerstringnoThe storage provider.
one of s3, s3_compatible, gcs, azure
bucketstringnoThe bucket (or Azure container).
prefixstringnoThe key prefix files are written under; empty or ending in /.
regionstring or nullyesThe region, where the provider has one.
endpointstring or nullyesAn S3-compatible store's address.
storage_accountstring or nullyesAzure's storage account.
auth_modestringnofederated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.
one of federated, stored
federationobject or object or object or any or nullyesA federated destination's values, null until they are sent.
formatstringnoThe file format.
one of jsonl, csv, tsv, json, parquet, avro
compressionstringnoThe files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.
one of gzip, zstd, none
format_optionsFormatOptionsnoCSV'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 optionalstringno, or ; for CSV; a tab for TSV.
one of ,, ;,
format_options.header optionalbooleannoA header row first.
default true
format_options.bom optionalbooleannoA UTF-8 byte order mark first, for spreadsheets.
default false
format_options.evidence_text optionalbooleannoMatched 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_versionstringnoThe detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).
one of v1, legacy
columnsarray of string or nullyesThe 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).
filterPushFilternoWhich detections a destination delivers; every field optional, all given must hold.
filter.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
filter.min_band optionalstringnoThe weakest strength delivered; max means text only reaches it.
one of off, low, medium, high, max
filter.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
filter.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
scheduleobject or object or objectnoWhen a destination delivers.
next_run_atstring (date-time) or nullyesThe next scheduled delivery; null while none is scheduled (setting up, paused).
start_atstring (date-time)noWhere the first delivery started.
cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
cursor.seqintegernoThe chunk's sequence number.
cursor.rowintegernoRows of that chunk read.
delivered_up_tostring (date-time) or nullyesWhen the newest done delivery finished; null before the first.
statusstringnosetting_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_atstring (date-time) or nullyesThe last connection test.
last_test_okboolean or nullyesWhether it passed.
last_test_errorstring or nullyesThe provider's words when it failed.
running_sincestring (date-time) or nullyesWhen the delivery running now started.
failing_sincestring (date-time) or nullyesWhen it began failing.
versionintegernoIts configuration's version, also the ETag.
created_atstring (date-time)noWhen it was created.
created_by_namestringnoWho created it (a person or a key's name).
updated_atstring (date-time)noIts last change.
credentialCredential or any or nullyesThe active credential, else the pending one, else null (always null for a federated destination).
last_deliveryDelivery or any or nullyesThe newest delivery, or null.
test_prefixstring or nullyesA 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

NameInTypeRequiredDescription
idpathstringyesA destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
If-MatchheaderstringnoThe 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

StatusMeaningBodyHeaders
200The destination now.application/json: DestinationX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Destination)

FieldTypeNullableDescription
idstringnoThe destination's id (dst_…).
namestringnoIts name, 1 to 60 characters.
providerstringnoThe storage provider.
one of s3, s3_compatible, gcs, azure
bucketstringnoThe bucket (or Azure container).
prefixstringnoThe key prefix files are written under; empty or ending in /.
regionstring or nullyesThe region, where the provider has one.
endpointstring or nullyesAn S3-compatible store's address.
storage_accountstring or nullyesAzure's storage account.
auth_modestringnofederated: our identity, trusted by your cloud (no secret stored); stored: a credential you give us, sealed.
one of federated, stored
federationobject or object or object or any or nullyesA federated destination's values, null until they are sent.
formatstringnoThe file format.
one of jsonl, csv, tsv, json, parquet, avro
compressionstringnoThe files' compression: gzip or none; zstd only for Parquet (inside the file), once Parquet files are available.
one of gzip, zstd, none
format_optionsFormatOptionsnoCSV'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 optionalstringno, or ; for CSV; a tab for TSV.
one of ,, ;,
format_options.header optionalbooleannoA header row first.
default true
format_options.bom optionalbooleannoA UTF-8 byte order mark first, for spreadsheets.
default false
format_options.evidence_text optionalbooleannoMatched 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_versionstringnoThe detection schema the files follow: v1; legacy for a managed legacy feed (see Managed legacy feeds).
one of v1, legacy
columnsarray of string or nullyesThe 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).
filterPushFilternoWhich detections a destination delivers; every field optional, all given must hold.
filter.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
filter.min_band optionalstringnoThe weakest strength delivered; max means text only reaches it.
one of off, low, medium, high, max
filter.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
filter.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
scheduleobject or object or objectnoWhen a destination delivers.
next_run_atstring (date-time) or nullyesThe next scheduled delivery; null while none is scheduled (setting up, paused).
start_atstring (date-time)noWhere the first delivery started.
cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
cursor.seqintegernoThe chunk's sequence number.
cursor.rowintegernoRows of that chunk read.
delivered_up_tostring (date-time) or nullyesWhen the newest done delivery finished; null before the first.
statusstringnosetting_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_atstring (date-time) or nullyesThe last connection test.
last_test_okboolean or nullyesWhether it passed.
last_test_errorstring or nullyesThe provider's words when it failed.
running_sincestring (date-time) or nullyesWhen the delivery running now started.
failing_sincestring (date-time) or nullyesWhen it began failing.
versionintegernoIts configuration's version, also the ETag.
created_atstring (date-time)noWhen it was created.
created_by_namestringnoWho created it (a person or a key's name).
updated_atstring (date-time)noIts last change.
credentialCredential or any or nullyesThe active credential, else the pending one, else null (always null for a federated destination).
last_deliveryDelivery or any or nullyesThe newest delivery, or null.
test_prefixstring or nullyesA 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

NameInTypeRequiredDescription
idpathstringyesA destination's id (dst_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
limitqueryintegernoRows in a page, 1 to 100; 100 when not given.
1 to 100; default 100
cursorquerystringnoThe next_cursor of a previous page of this log; the page after it. A value this endpoint did not give is 400.

Responses

StatusMeaningBodyHeaders
200A page of the log.application/json: DeliveriesPageX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (DeliveriesPage)

FieldTypeNullableDescription
dataarray of DeliverynoThe deliveries, newest first.
data[].idstringnoThe delivery's id (dlv_…).
data[].statusstringnoWhere it is; empty when there was nothing to deliver.
one of planned, rendering, uploading, done, empty, failed
data[].fromStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
data[].from.seqintegernoThe chunk's sequence number.
data[].from.rowintegernoRows of that chunk read.
data[].toStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
data[].to.seqintegernoThe chunk's sequence number.
data[].to.rowintegernoRows of that chunk read.
data[].rowsinteger or nullyesDetections delivered.
data[].partsinteger or nullyesFiles written.
data[].bytesinteger or nullyesBytes written.
data[].manifest_keystring or nullyesThe manifest's key in your bucket; it lists the parts.
data[].attemptsintegernoFailed attempts so far.
data[].first_failed_atstring (date-time) or nullyesThe first failed attempt.
data[].errorstring or nullyesThe provider's status and error code, verbatim.
data[].triggerstringnoWhat started it.
one of schedule, run_now, resume
data[].started_atstring (date-time)noWhen it started.
data[].finished_atstring (date-time) or nullyesWhen it finished.
data[].stepobject or any or nullyesWhile rendering or uploading, the part being worked on and how many are planned so far.
next_cursorstring or nullyesThe next page's cursor, or null.
has_morebooleannoTrue 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

StatusMeaningBodyHeaders
200The endpoints.application/json: WebhooksPageX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (WebhooksPage)

FieldTypeNullableDescription
dataarray of WebhooknoThe endpoints, newest first.
data[].idstringnoThe endpoint's id (whk_…).
data[].urlstringnoWhere messages are sent (a public https address).
data[].ruleWebhookRulenoWhat an endpoint receives; every field optional, all given must hold.
data[].rule.events optionalarray of stringnoNew detections, changed ones, or both (the default).
each one of created, updated
data[].rule.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
data[].rule.min_band optionalstringnoThe weakest strength sent.
one of off, low, medium, high, max
data[].rule.customer optionalbooleannoCustomers only (true) or non-customers only (false); only once the subscription has a Sites list with customers.
data[].rule.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
data[].rule.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
data[].statusstringnofailing while messages fail; disabled when the system stopped it after 3 days of failing.
one of active, paused, failing, disabled
data[].failing_sincestring (date-time) or nullyesWhen it began failing.
data[].secret_set_atstring (date-time)noWhen the signing secret was made.
data[].secret_set_by_namestringnoWho made it (a person or a key's name).
data[].previous_secret_untilstring (date-time) or nullyesAfter a rotation, until when messages are also signed with the old secret.
data[].cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
data[].cursor.seqintegernoThe chunk's sequence number.
data[].cursor.rowintegernoRows of that chunk read.
data[].versionintegernoIts configuration's version, also the ETag.
data[].created_atstring (date-time)noWhen it was created.
data[].created_by_namestringnoWho created it (a person or a key's name).
data[].updated_atstring (date-time)noIts last change.
data[].last_messageMessage or any or nullyesThe newest message, or null.
next_cursorany or nullyesAlways null (one page).
has_morebooleannoAlways 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

NameInTypeRequiredDescription
Idempotency-Keyheaderstringno1 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:

FieldTypeRequiredDescription
urlstringyesA public https address; not an IP address, not a private or local name.
ruleWebhookRulenoWhat an endpoint receives; every field optional, all given must hold.

Responses

StatusMeaningBodyHeaders
201Created, 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: WebhookWithSecretX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag, Idempotent-Replayed
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
413content_too_large: the body is larger than 64 KB (65,536 bytes).application/problem+json: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
422idempotency_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
429rate_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

201 body (WebhookWithSecret)

FieldTypeNullableDescription
idstringnoThe endpoint's id (whk_…).
urlstringnoWhere messages are sent (a public https address).
ruleWebhookRulenoWhat an endpoint receives; every field optional, all given must hold.
rule.events optionalarray of stringnoNew detections, changed ones, or both (the default).
each one of created, updated
rule.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
rule.min_band optionalstringnoThe weakest strength sent.
one of off, low, medium, high, max
rule.customer optionalbooleannoCustomers only (true) or non-customers only (false); only once the subscription has a Sites list with customers.
rule.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
rule.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
statusstringnofailing while messages fail; disabled when the system stopped it after 3 days of failing.
one of active, paused, failing, disabled
failing_sincestring (date-time) or nullyesWhen it began failing.
secret_set_atstring (date-time)noWhen the signing secret was made.
secret_set_by_namestringnoWho made it (a person or a key's name).
previous_secret_untilstring (date-time) or nullyesAfter a rotation, until when messages are also signed with the old secret.
cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
cursor.seqintegernoThe chunk's sequence number.
cursor.rowintegernoRows of that chunk read.
versionintegernoIts configuration's version, also the ETag.
created_atstring (date-time)noWhen it was created.
created_by_namestringnoWho created it (a person or a key's name).
updated_atstring (date-time)noIts last change.
last_messageMessage or any or nullyesThe newest message, or null.
secretstring or nullyesThe 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

NameInTypeRequiredDescription
idpathstringyesA webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.

Responses

StatusMeaningBodyHeaders
200The endpoint.application/json: WebhookX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Webhook)

FieldTypeNullableDescription
idstringnoThe endpoint's id (whk_…).
urlstringnoWhere messages are sent (a public https address).
ruleWebhookRulenoWhat an endpoint receives; every field optional, all given must hold.
rule.events optionalarray of stringnoNew detections, changed ones, or both (the default).
each one of created, updated
rule.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
rule.min_band optionalstringnoThe weakest strength sent.
one of off, low, medium, high, max
rule.customer optionalbooleannoCustomers only (true) or non-customers only (false); only once the subscription has a Sites list with customers.
rule.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
rule.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
statusstringnofailing while messages fail; disabled when the system stopped it after 3 days of failing.
one of active, paused, failing, disabled
failing_sincestring (date-time) or nullyesWhen it began failing.
secret_set_atstring (date-time)noWhen the signing secret was made.
secret_set_by_namestringnoWho made it (a person or a key's name).
previous_secret_untilstring (date-time) or nullyesAfter a rotation, until when messages are also signed with the old secret.
cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
cursor.seqintegernoThe chunk's sequence number.
cursor.rowintegernoRows of that chunk read.
versionintegernoIts configuration's version, also the ETag.
created_atstring (date-time)noWhen it was created.
created_by_namestringnoWho created it (a person or a key's name).
updated_atstring (date-time)noIts last change.
last_messageMessage or any or nullyesThe 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

NameInTypeRequiredDescription
idpathstringyesA webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
If-MatchheaderstringnoThe 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:

FieldTypeRequiredDescription
urlstringnoA public https address.
ruleWebhookRulenoWhat an endpoint receives; every field optional, all given must hold.

Responses

StatusMeaningBodyHeaders
200Changed, or already so.application/json: WebhookX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
413content_too_large: the body is larger than 64 KB (65,536 bytes).application/problem+json: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Webhook)

FieldTypeNullableDescription
idstringnoThe endpoint's id (whk_…).
urlstringnoWhere messages are sent (a public https address).
ruleWebhookRulenoWhat an endpoint receives; every field optional, all given must hold.
rule.events optionalarray of stringnoNew detections, changed ones, or both (the default).
each one of created, updated
rule.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
rule.min_band optionalstringnoThe weakest strength sent.
one of off, low, medium, high, max
rule.customer optionalbooleannoCustomers only (true) or non-customers only (false); only once the subscription has a Sites list with customers.
rule.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
rule.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
statusstringnofailing while messages fail; disabled when the system stopped it after 3 days of failing.
one of active, paused, failing, disabled
failing_sincestring (date-time) or nullyesWhen it began failing.
secret_set_atstring (date-time)noWhen the signing secret was made.
secret_set_by_namestringnoWho made it (a person or a key's name).
previous_secret_untilstring (date-time) or nullyesAfter a rotation, until when messages are also signed with the old secret.
cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
cursor.seqintegernoThe chunk's sequence number.
cursor.rowintegernoRows of that chunk read.
versionintegernoIts configuration's version, also the ETag.
created_atstring (date-time)noWhen it was created.
created_by_namestringnoWho created it (a person or a key's name).
updated_atstring (date-time)noIts last change.
last_messageMessage or any or nullyesThe 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

NameInTypeRequiredDescription
idpathstringyesA webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
If-MatchheaderstringnoThe 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

StatusMeaningBodyHeaders
204Deleted. The ETag is its last version.noneX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-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

NameInTypeRequiredDescription
idpathstringyesA webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
If-MatchheaderstringnoThe 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-Keyheaderstringno1 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

StatusMeaningBodyHeaders
200The endpoint with its new secret; or, for a repeated Idempotency-Key, the endpoint now with secret: null.application/json: WebhookWithSecretX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag, Idempotent-Replayed
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
413content_too_large: the body is larger than 64 KB (65,536 bytes).application/problem+json: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
422idempotency_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
429rate_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (WebhookWithSecret)

FieldTypeNullableDescription
idstringnoThe endpoint's id (whk_…).
urlstringnoWhere messages are sent (a public https address).
ruleWebhookRulenoWhat an endpoint receives; every field optional, all given must hold.
rule.events optionalarray of stringnoNew detections, changed ones, or both (the default).
each one of created, updated
rule.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
rule.min_band optionalstringnoThe weakest strength sent.
one of off, low, medium, high, max
rule.customer optionalbooleannoCustomers only (true) or non-customers only (false); only once the subscription has a Sites list with customers.
rule.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
rule.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
statusstringnofailing while messages fail; disabled when the system stopped it after 3 days of failing.
one of active, paused, failing, disabled
failing_sincestring (date-time) or nullyesWhen it began failing.
secret_set_atstring (date-time)noWhen the signing secret was made.
secret_set_by_namestringnoWho made it (a person or a key's name).
previous_secret_untilstring (date-time) or nullyesAfter a rotation, until when messages are also signed with the old secret.
cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
cursor.seqintegernoThe chunk's sequence number.
cursor.rowintegernoRows of that chunk read.
versionintegernoIts configuration's version, also the ETag.
created_atstring (date-time)noWhen it was created.
created_by_namestringnoWho created it (a person or a key's name).
updated_atstring (date-time)noIts last change.
last_messageMessage or any or nullyesThe newest message, or null.
secretstring or nullyesThe 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

NameInTypeRequiredDescription
idpathstringyesA webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
If-MatchheaderstringnoThe 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

StatusMeaningBodyHeaders
200The endpoint now.application/json: WebhookX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Webhook)

FieldTypeNullableDescription
idstringnoThe endpoint's id (whk_…).
urlstringnoWhere messages are sent (a public https address).
ruleWebhookRulenoWhat an endpoint receives; every field optional, all given must hold.
rule.events optionalarray of stringnoNew detections, changed ones, or both (the default).
each one of created, updated
rule.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
rule.min_band optionalstringnoThe weakest strength sent.
one of off, low, medium, high, max
rule.customer optionalbooleannoCustomers only (true) or non-customers only (false); only once the subscription has a Sites list with customers.
rule.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
rule.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
statusstringnofailing while messages fail; disabled when the system stopped it after 3 days of failing.
one of active, paused, failing, disabled
failing_sincestring (date-time) or nullyesWhen it began failing.
secret_set_atstring (date-time)noWhen the signing secret was made.
secret_set_by_namestringnoWho made it (a person or a key's name).
previous_secret_untilstring (date-time) or nullyesAfter a rotation, until when messages are also signed with the old secret.
cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
cursor.seqintegernoThe chunk's sequence number.
cursor.rowintegernoRows of that chunk read.
versionintegernoIts configuration's version, also the ETag.
created_atstring (date-time)noWhen it was created.
created_by_namestringnoWho created it (a person or a key's name).
updated_atstring (date-time)noIts last change.
last_messageMessage or any or nullyesThe 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

NameInTypeRequiredDescription
idpathstringyesA webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
If-MatchheaderstringnoThe 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

StatusMeaningBodyHeaders
200The endpoint now.application/json: WebhookX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Webhook)

FieldTypeNullableDescription
idstringnoThe endpoint's id (whk_…).
urlstringnoWhere messages are sent (a public https address).
ruleWebhookRulenoWhat an endpoint receives; every field optional, all given must hold.
rule.events optionalarray of stringnoNew detections, changed ones, or both (the default).
each one of created, updated
rule.content_types optionalarray of stringnoA subset of what the subscription carries.
each one of text, image
rule.min_band optionalstringnoThe weakest strength sent.
one of off, low, medium, high, max
rule.customer optionalbooleannoCustomers only (true) or non-customers only (false); only once the subscription has a Sites list with customers.
rule.domains optionalarray of stringnoRegistrable domains, at most 50.
at most 50 values
rule.publisher_ids optionalarray of integernoPublisher ids, at most 50.
at most 50 values
statusstringnofailing while messages fail; disabled when the system stopped it after 3 days of failing.
one of active, paused, failing, disabled
failing_sincestring (date-time) or nullyesWhen it began failing.
secret_set_atstring (date-time)noWhen the signing secret was made.
secret_set_by_namestringnoWho made it (a person or a key's name).
previous_secret_untilstring (date-time) or nullyesAfter a rotation, until when messages are also signed with the old secret.
cursorStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
cursor.seqintegernoThe chunk's sequence number.
cursor.rowintegernoRows of that chunk read.
versionintegernoIts configuration's version, also the ETag.
created_atstring (date-time)noWhen it was created.
created_by_namestringnoWho created it (a person or a key's name).
updated_atstring (date-time)noIts last change.
last_messageMessage or any or nullyesThe 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

NameInTypeRequiredDescription
idpathstringyesA webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
If-MatchheaderstringnoThe 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

StatusMeaningBodyHeaders
200The attempt.application/json: AttemptX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
429rate_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Attempt)

FieldTypeNullableDescription
okbooleannoWhether your endpoint accepted it (a 2xx).
statusinteger or nullyesYour endpoint's HTTP status; null when it could not be reached.
latency_msintegernoHow long it took.
atstring (date-time)noWhen it was sent.
errorstring or nullyesWhy it failed.
message_idstringnoThe 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

NameInTypeRequiredDescription
idpathstringyesA webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
limitqueryintegernoRows in a page, 1 to 100; 100 when not given.
1 to 100; default 100
cursorquerystringnoThe next_cursor of a previous page of this log; the page after it. A value this endpoint did not give is 400.

Responses

StatusMeaningBodyHeaders
200A page of the log.application/json: MessagesPageX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
429rate_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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (MessagesPage)

FieldTypeNullableDescription
dataarray of MessagenoThe messages, newest first.
data[].idstringnoThe message's id (msg_…), sent as webhook-id (a replay sends its original's).
data[].kindstringnoDetections, a test, or a message sent again.
one of batch, test, replay
data[].replay_ofstring or nullyesThe original message of a replay.
data[].fromStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
data[].from.seqintegernoThe chunk's sequence number.
data[].from.rowintegernoRows of that chunk read.
data[].toStreamPositionnoA position in the subscription's change stream (a chunk and the rows of it read).
data[].to.seqintegernoThe chunk's sequence number.
data[].to.rowintegernoRows of that chunk read.
data[].detectionsintegernoDetections in it.
data[].statusstringnopending while it is being sent (with retries), then delivered or failed.
one of pending, delivered, failed
data[].attemptsintegernoAttempts so far.
data[].last_statusinteger or nullyesYour endpoint's HTTP status at the last attempt.
data[].last_latency_msinteger or nullyesHow long the last attempt took.
data[].last_errorstring or nullyesWhy the last attempt failed.
data[].next_attempt_atstring (date-time) or nullyesThe next retry of a pending message.
data[].first_failed_atstring (date-time) or nullyesThe first failed attempt.
data[].created_atstring (date-time)noWhen it was made.
data[].delivered_atstring (date-time) or nullyesWhen your endpoint accepted it.
next_cursorstring or nullyesThe next page's cursor, or null.
has_morebooleannoTrue 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

NameInTypeRequiredDescription
idpathstringyesA webhook endpoint's id (whk_…). Another subscription's, a deleted one or an unknown id is 404, whichever it is.
message_idpathstringyesA message of this endpoint (msg_…), from its log.
If-MatchheaderstringnoThe 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

StatusMeaningBodyHeaders
200The attempt.application/json: AttemptX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
400invalid_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
401unauthorized: no credential, or one that is malformed, unknown, expired or revoked.application/problem+json: ProblemX-Request-Id, Cache-Control, WWW-Authenticate
403forbidden: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
404not_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
405method_not_allowed: the path exists but does not answer this method. Allow lists the methods it does answer.application/problem+json: ProblemX-Request-Id, Cache-Control, Allow
409limit_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
412precondition_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, ETag
429rate_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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy, Retry-After
500internal: 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: ProblemX-Request-Id, Cache-Control, RateLimit-Limit, RateLimit-Policy
503unavailable: 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: ProblemX-Request-Id, Cache-Control, Retry-After, RateLimit-Limit, RateLimit-Policy

200 body (Attempt)

FieldTypeNullableDescription
okbooleannoWhether your endpoint accepted it (a 2xx).
statusinteger or nullyesYour endpoint's HTTP status; null when it could not be reached.
latency_msintegernoHow long it took.
atstring (date-time)noWhen it was sent.
errorstring or nullyesWhy it failed.
message_idstringnoThe 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.

FieldTypeNullableContent typesDescription
idstringnotext, image<t|i>.<subscription>.<source internal id>.<article id>, e.g. t.9001.5000001.7000001. Stable forever; opaque to customers
versionintegernotext, image1 on first sight; +1 whenever a customer-visible field changes
at least 1
eventstringnotext, imagecreated or updated. Present on the change stream only: /v1/detections and /v1/detections/{id} answer current states and leave it out
one of created, updated
content_typestringnotext, imagetext or image
one of text, image
match_typestringnotext, imagesentence_fingerprint for text, image_fingerprint for images
one of sentence_fingerprint, image_fingerprint
subscription_idintegernotext, imageThe subscription the detection belongs to
first_detected_atstring (date-time)notext, imageOurs: when the match first reached us. Backfilled rows are flagged (first_detected_estimated)
first_detected_estimatedbooleannotext, imageTrue when first_detected_at is estimated: a backfilled row
last_scored_atstring (date-time)notext, imageThe export's matched_at
exported_atstring (date-time)notext, imageWhen EzyInsights wrote the row
sourceobjectnoThe agency's item.
source.idstring or nullyestext, imageThe agency's own id: a URN, a NewsML id, a UUID
source.internal_idintegernotext, imageEzyInsights' id; links into the dashboard
source.published_atstring (date-time) or nullyestext, imageFor images, the real publish time, not the record's creation
source.languagestring or nullyestextThe wire story's language
source.syndicatedboolean or nullyestextWhether the wire story is syndicated
source.sentencesinteger or nullyestextThe wire story's sentence count, once exported
source.headlinestring or nullyestextThe 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_urlstring (uri)noimageOur 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_urlstring (uri) or nullyesimageWhere the agency's photo came from (imagewire_source_uri)
strengthobjectnoHow strong the match is.
strength.scorenumbernotext, imageText: usage % (0–100); image: score (0–99)
strength.bandstringnotext, imageText 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/60
one of off, low, medium, high, max
strength.matched_sentencesinteger or nullyestextThe export's estimate, in wire-story sentences
strength.article_sentencesinteger or nullyestextThe publisher article's sentence count
articleobjectnoThe publisher article the item was found in.
article.idintegernotext, imageThe publisher article (content_story_id)
article.urlstring (uri) or nullyestext, imageCanonical URL
article.domainstring or nullyestext, imageRegistrable domain
article.published_atstring (date-time) or nullyestext, imageUnknown for 45% of text rows, 12% of image rows
article.headlinestring or nullyestext, imageThe publisher article's headline; null until the exports carry it
article.publisherobject or nullyesThe publisher, or null when its id is unknown (the detection then carries the domain only).
article.publisher.idintegeryestext, imageThe real publisher id
article.publisher.namestring or nullyestext, imageTrimmed
article.printbooleannotextWhether the publisher is a print title. For print articles, article.url is null outside the agencies licensed for NLA's metadata
article.image_urlstring (uri) or nullyesimageThe publisher's copy (matched_image_url)
evidenceTextEvidenceEnvelopenoHow 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.kindstringnoWhose evidence this is; image evidence will come with kind image.
always text
evidence.statusstringnostored 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_atstring (date-time)noThe match the detection stands on (its last_scored_at).
evidence.expires_atstring (date-time)nomatched_at + 45 days: after it, the record is no longer kept.
evidence.article_textstringnoWhat 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.recordstring (uri)noGET /v1/detections/{id}/evidence.
evidence.packstring (uri)noGET /v1/detections/{id}/evidence/pack.
customerboolean or nullyestext, imageWhether the publisher is on the subscription's customer list; null until that list is exported
classificationstring or nullyestext, imagelicensed, potentially_unlicensed, unknown; null until classified
one 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.

FieldTypeNullableDescription
typestring (uri)noThe 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.
titlestringnoThe type's title, as above.
statusintegernoThe HTTP status.
detailstringnoWhat was wrong with this request, in plain English.
request_idstring (uuid)noThe request's id, the same as X-Request-Id.

OAuthError

The token endpoint's errors (RFC 6749 §5.2).

FieldTypeNullableDescription
errorstringno
one of invalid_request, invalid_client, unsupported_grant_type, invalid_scope
error_descriptionstringnoWhat was wrong, in plain English.