The API, endpoint by endpoint.

Generated from the OpenAPI contract. Use an approved bearer key for gated data. Not seen means unknown, never safe.

Access & integration overview →Download OpenAPI →

Examples show request syntax, not live observations. Replace placeholders locally. Access requests use the signed form at Request API access; its token and proof of work are required. Rate and daily quotas depend on your plan and endpoint. Retry after the Retry-After interval on 429 responses. Consult response headers for cache policy.

Stats

GET

`/api/v1/stats/overview`

Public; optional approved key

Headline numbers for the index page

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/overview'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/overview",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/overview", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`updated_at`	`string`	—
`ai`	`object`	AI traffic measured honestly over the trailing 24h window. Web cells use HTTP(S) requests as the denominator; non-web service probes (SSH, Redis, ...) cannot be AI crawler requests and are reported separately. Verification tiers are event-local snapshots and are never reconstructed backwards.
`totals`	`object`	—
`last_24h`	`object`	—
`by_category_24h`	`object[]`	—
`top_bots_24h`	`object[]`	—
`regions`	`object[]`	—

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stats/credentials`

Public; optional approved key

Planned — delayed aggregate credential-attack intelligence

Publication-gated delayed credential-attack aggregates. Returns 404 while publication is disabled. Anonymous aggregate data is delayed at least 24 hours. Reviewed password and username vocabularies only; omitted cells are counted in withheld.cells. Supports 7d and 30d windows.

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`window`	query · string	Allowed: 7d, 30d. Default: 7d.

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/credentials'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/credentials",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/credentials", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`breach_reuse`	`object`	Counts only for the same completed-UTC-day window. overall and each by_protocol metric have status published or withheld. Published metrics include checked_groups (distinct observed password groups with a stored breach check), seen_groups (checked groups with seen=true), share (seen_groups/checked_groups), attempts_share (all credential attempts whose group is seen divided by all credential attempts), and checked_at_latest (latest stored check timestamp). Withheld metrics contain only status; requires at least 50 checked groups, 100 attempts and 20 source networks. Small protocol cells are omitted. No passwords, usernames, hashes or lookup material are included in this field.
`generated_at`	`string`	—
`window`	`object`	—
`delay_hours`	`integer`	—
`thresholds`	`object`	—
`totals`	`object`	—
`by_protocol`	`object[]`	—
`modes`	`object[]`	—
`modes_by_protocol`	`object[]`	Each split requires the cell threshold; share is of all attempts within that protocol. Omitted cells increment withheld.cells.
`ai_tooling`	`object`	—
`top_usernames`	`object[]`	—
`top_passwords`	`object[]`	—
`other_password_share`	`number`	—
`daily`	`object[]`	—
`withheld`	`object`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
404 Publication disabled
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stats/timeseries`

Public; optional approved key

Time series for a metric

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`metric` (required)	query · string	Allowed: events, unique_ips, ai_share, canary_hits, honeytoken_uses.
`interval`	query · string	Allowed: 1h, 1d. Default: 1h.
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`category`	query · string
`region`	query · string
`bot_id`	query · string

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/timeseries'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/timeseries",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/timeseries", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`metric`	`string`	—
`interval`	`string`	—
`since`	`string`	—
`until`	`string`	—
`points`	`object[]`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stats/top`

Public; optional approved key

Top-N breakdown

Public output contains at most 10 entries; aggregate cells below 3 events or 2 distinct sources are suppressed.

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`by` (required)	query · string	Allowed: path, ip, asn, country, bot, trap, ua, cve, persona, region.
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`category`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`region`	query · string
`limit`	query · integer	Default: 10. Maximum: 100.

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/top'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/top",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/top", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`by`	`string`	—
`since`	`string`	—
`items`	`object[]`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/regions`

Public; optional approved key

Sensor/region status and volume

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/regions'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/regions",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/regions", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`sensor_id`	`string`	—
`region`	`string`	—
`provider`	`string \| null`	—
`kind`	`string`	—
`hostname`	`string \| null`	—
`enabled`	`boolean`	—
`last_heartbeat`	`string \| null`	—
`healthy`	`boolean`	—
`events_24h`	`integer`	—
`events_total`	`integer`	—

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/honeytokens/stats`

Public; optional approved key

Honeytoken planting vs use, harvest-to-use latency

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.

Example requests

curl

curl 'https://mothlight.ai/api/v1/honeytokens/stats'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/honeytokens/stats",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/honeytokens/stats", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`planted`	`integer`	—
`used`	`integer`	—
`median_latency_sec`	`number \| null`	—
`by_placement`	`object[]`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stats/pulse`

Public; optional approved key

Live aggregate pulse

Last-hour aggregates with previous-hour comparison. Source-sensitive cells may be withheld. No event rows are returned. Anonymous responses are cached for 30 seconds.

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/pulse'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/pulse",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/pulse", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`window`	`object`	—
`updatedAt`	`string`	—
`minutes`	`object[]`	—
`totals`	`object`	—
`topCountries`	`object[]`	—
`withheldCountries`	`integer`	—
`map`	`object`	Country-level flow aggregates, with suppressed bucket/event and withheld-flow counts.

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stats/sample`

Public; optional approved key

Public sample and weekly dataset

Anonymous coarse 1-in-100 sample: at most 20 newest cards, delayed at least 60 minutes. Weekly CC BY 4.0 view contains at most 500 rows from the previous complete ISO week, at least seven days old. No pagination.

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/sample'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/sample",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/sample", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`sample`	`object`	—
`dataset`	`object`	—

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stats/unknown`

Public; optional approved key

Unknown traffic explained

Delayed 24-hour aggregate explanation of traffic without a verified known identity. Withheld cells are null, never zero. Behavioral labels are inference, not operator attribution.

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/unknown'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/unknown",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/unknown", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`updated_at`	`string`	—
`window`	`object`	—
`totals`	`object`	—
`by_family`	`object[]`	—
`by_protocol`	`object[]`	—
`by_stage`	`object[]`	—
`top_clusters`	`object[]`	—
`networks`	`object \| null`	—
`withheld`	`object`	—
`methodology_version`	`string`	—

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

Bots

GET

`/api/v1/bots`

Public; optional approved key

Leaderboard of labelled actors

Anonymous/read pages allow 50 rows with a 200-row cursor boundary. Gated event scopes allow 200-row pages. Public aggregate cells below 3 events or 2 distinct sources are suppressed.

Authentication: Authorization: Bearer YOUR_API_KEY. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`category`	query · string
`region`	query · string
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`q`	query · string	search in name/code/codename
`sort`	query · string	Allowed: events, last_seen, ai, confidence. Default: events.
`limit`	query · integer	Maximum 200 rows per page for events-scope callers; read scope cannot retrieve event rows. Default: 50. Minimum: 1. Maximum: 200.
`cursor`	query · string	Opaque next_cursor; public event offsets cannot reach or exceed 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/bots' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/bots",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/bots", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`items`	`object[]`	—
`next_cursor`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/bots/{bot_id}`

Public; optional approved key

Bot profile with public or scoped metadata

Public/read profiles omit signal weights, signal detail and internal notes. Gated event scopes (events, stream, export or raw) unlock those fields, subject to read-model redaction.

Authentication: Authorization: Bearer YOUR_API_KEY. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`bot_id` (required)	path · string	stable id (openai-gptbot

Example requests

curl

curl 'https://mothlight.ai/api/v1/bots/YOUR_BOT_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/bots/YOUR_BOT_ID",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/bots/YOUR_BOT_ID", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`id`	`string`	—
`code`	`string`	—
`codename`	`string \| null`	—
`name`	`string`	—
`vendor`	`string \| null`	—
`category`	`string`	—
`confidence`	`integer`	—
`ai_likelihood`	`integer`	—
`verification`	`string`	—
`events_24h`	`integer \| null`	Null = withheld by the publication rule (fewer than 3 events or fewer than 2 distinct sources), never zero.
`events_total`	`integer \| null`	Null = withheld by the publication rule, never zero.
`ip_count`	`integer \| null`	Null = withheld by the publication rule, never zero.
`counts_suppressed`	`boolean`	True when headline counts are withheld, typically for single-source actors.
`volume_band`	`string \| null`	Coarse non-identifying volume band for suppressed actors (e.g. 1k–10k requests); null when counts are publishable.
`first_seen`	`string`	—
`last_seen`	`string`	—
`countries`	`string[]`	—
`robots_compliance`	`number \| null`	—
`signals`	`object[]`	—
`top_paths`	`object[]`	—
`personas`	`string[]`	—
`regions`	`string[]`	—
`cves`	`string[]`	—
`canary_follows`	`integer \| null`	Null = below publication threshold, never a fabricated zero.
`honeytoken_uses`	`integer \| null`	Null = below publication threshold, never a fabricated zero.
`evidence_tiers`	`object[]`	—
`known_bot`	`object \| null`	—
`notes`	`string \| null`	Omitted for anonymous/read profiles.

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/bots/{bot_id}/events`

Professional or Enterprise

Events for a bot

Requires an approved key with events scope (Professional or Enterprise), or manually contracted raw scope. Anonymous requests return 401; read-only keys return 403. Professional: at least 15-minute delay and up to 30-day history. Enterprise: no minimum delay and up to 365-day history. Lists allow up to 200 rows per page. Sensitive fields remain subject to redaction.

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`bot_id` (required)	path · string
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`category`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`region`	query · string
`limit`	query · integer	Maximum 200 rows per page for events-scope callers; read scope cannot retrieve event rows. Default: 50. Minimum: 1. Maximum: 200.
`cursor`	query · string	Opaque next_cursor; public event offsets cannot reach or exceed 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/bots/YOUR_BOT_ID/events' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/bots/YOUR_BOT_ID/events",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/bots/YOUR_BOT_ID/events", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`items`	`object[]`	—
`next_cursor`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/bots/{bot_id}/timeseries`

Public; optional approved key

Activity time series for a bot

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`bot_id` (required)	path · string
`interval`	query · string	Allowed: 1h, 1d. Default: 1d.
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.

Example requests

curl

curl 'https://mothlight.ai/api/v1/bots/YOUR_BOT_ID/timeseries'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/bots/YOUR_BOT_ID/timeseries",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/bots/YOUR_BOT_ID/timeseries", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`metric`	`string`	—
`interval`	`string`	—
`since`	`string`	—
`until`	`string`	—
`points`	`object[]`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/robots-compliance`

Public; optional approved key

robots.txt compliance per bot

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`category`	query · string

Example requests

curl

curl 'https://mothlight.ai/api/v1/robots-compliance'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/robots-compliance",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/robots-compliance", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`bot_id`	`string`	—
`code`	`string`	—
`name`	`string`	—
`vendor`	`string \| null`	—
`category`	`string`	—
`verification`	`string`	—
`rules_tested`	`integer`	—
`violations`	`integer`	—
`compliance`	`number`	—
`last_violation_at`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/known-bots`

Public; optional approved key

Curated registry of known bots (UA tokens, vendor, verification method)

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/known-bots'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/known-bots",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/known-bots", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`slug`	`string`	—
`name`	`string`	—
`vendor`	`string`	—
`category`	`string`	—
`robots_token`	`string \| null`	—
`verification_method`	`string`	—
`docs_url`	`string \| null`	—
`purpose`	`string \| null`	—

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

Events

GET

`/api/v1/events`

Professional or Enterprise

Event list

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`category`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`region`	query · string
`trap`	query · string
`tag`	query · string
`ip`	query · string	Exact IP filter for events-scope callers.
`limit`	query · integer	Maximum 200 rows per page for events-scope callers; read scope cannot retrieve event rows. Default: 50. Minimum: 1. Maximum: 200.
`cursor`	query · string	Opaque next_cursor; public event offsets cannot reach or exceed 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/events' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/events",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/events", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`items`	`object[]`	—
`next_cursor`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/events/recent`

Professional or Enterprise

Recent events (alias of /events)

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`category`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`region`	query · string
`trap`	query · string
`tag`	query · string
`ip`	query · string	Exact IP filter for events-scope callers.
`limit`	query · integer	Maximum 200 rows per page for events-scope callers; read scope cannot retrieve event rows. Default: 50. Minimum: 1. Maximum: 200.
`cursor`	query · string	Opaque next_cursor; public event offsets cannot reach or exceed 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/events/recent' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/events/recent",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/events/recent", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`items`	`object[]`	—
`next_cursor`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/events/{event_id}`

Professional or Enterprise

Event detail

Requires an approved key with events scope (Professional or Enterprise), or manually contracted raw scope. Anonymous requests return 401; read-only keys return 403. Returns redacted event detail for the requested id, or 404 when absent. Payload summary and sensitive metadata remain subject to read-model redaction; full private payload bytes require the raw training export.

Authentication: Authorization: Bearer YOUR_API_KEY. One request counts toward the daily request quota. No event-list row debit.

Parameters

Name	Location / type	Details
`event_id` (required)	path · string

Example requests

curl

curl 'https://mothlight.ai/api/v1/events/YOUR_EVENT_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/events/YOUR_EVENT_ID",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/events/YOUR_EVENT_ID", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`id`	`string`	—
`ts`	`string`	—
`sensor`	`string`	—
`region`	`string \| null`	—
`persona`	`string \| null`	—
`proto`	`string`	—
`method`	`string \| null`	—
`path`	`string \| null`	—
`src_ip`	`string`	Public defaults mask non-vendors; verified AIC/AIA/SEC/MON vendors may be disclosed. Gated event scopes receive full IPs.
`country`	`string \| null`	—
`asn`	`integer \| null`	—
`as_org`	`string \| null`	—
`ua`	`string \| null`	—
`bot_id`	`string \| null`	—
`bot_code`	`string \| null`	—
`category`	`string`	—
`confidence`	`integer`	—
`ai_likelihood`	`integer`	—
`tags`	`string[]`	—
`trap_id`	`string \| null`	—
`response_status`	`integer \| null`	—
`credential_mode`	`string \| null`	Professional+ offline classification; null when no credential attempt was classified.
`credential_campaign`	`object \| null`	—
`payload_summary`	`object \| null`	Gated only; redacted payload summary rather than full private bytes.
`query`	`string \| null`	—
`headers`	`object \| null`	—
`body_sample`	`string \| null`	—
`body_sha256`	`string \| null`	—
`body_size`	`integer \| null`	—
`signals`	`object[]`	—
`cve_ids`	`string[]`	—
`ja4`	`string \| null`	—
`geo`	`object \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stream`

Researcher aggregate; Professional or Enterprise per-event

Aggregate SSE (approved key) or scoped per-event SSE

text/event-stream. Anonymous calls return 401 with the request-form URL. Approved read keys and keys without stream/raw receive aggregate frames containing arrays of { minute, category, count }, with cells suppressed below 3 events or 2 source buckets. Public event-window bounds apply to callers without a gated event scope. stream or raw grants proprietary per-event frames (EventSummary JSON). Heartbeat every 15 s; maximum connection 60 s. Reconnect as needed. Last-Event-ID suppresses that ID in gated mode, not durable replay.

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quota and connection rate limit; per-event access checks daily row allowance.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`Last-Event-ID`	header · string	Optional gated event ID to suppress on reconnect.
`category`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`region`	query · string

Example requests

curl

curl 'https://mothlight.ai/api/v1/stream' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stream",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stream", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · text/event-stream · SSE stream

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/canaries`

Professional or Enterprise

Canary trigger rows

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`category`	query · string
`region`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`limit`	query · integer	Maximum 200 rows per page for events-scope callers; read scope cannot retrieve event rows. Default: 50. Minimum: 1. Maximum: 200.
`cursor`	query · string	Opaque next_cursor; public event offsets cannot reach or exceed 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/canaries' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/canaries",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/canaries", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`items`	`object[]`	—
`next_cursor`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/prompts`

Professional or Enterprise

Redacted prompt captures

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`category`	query · string
`region`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`limit`	query · integer	Maximum 200 rows per page for events-scope callers; read scope cannot retrieve event rows. Default: 50. Minimum: 1. Maximum: 200.
`cursor`	query · string	Opaque next_cursor; public event offsets cannot reach or exceed 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/prompts' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/prompts",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/prompts", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`items`	`object[]`	—
`next_cursor`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

Credentials

GET

`/api/v1/credentials/blocklist`

Professional or Enterprise

Sanitized attacker-dictionary blocklist (professional+)

Sanitized attacker-dictionary feed for Professional or Enterprise. Broad confidence is the default; high confidence is more selective. JSON returns metadata and entries; TXT returns one value per line. Entra returns at most 1,000 eligible values of 4–16 characters. Breach metadata can be null when unchecked; unknown never means safe.

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`format`	query · string	Output format. Allowed: txt, json, entra. Default: json.
`confidence`	query · string	Feed confidence tier. Allowed: broad, high. Default: broad.
`leaked`	query · string	Include only entries confirmed in breach corpora. Allowed: only.
`sort`	query · string	Priority places confirmed leaked entries first, then sources and attempts. Allowed: sources, priority. Default: sources.

Example requests

curl

curl 'https://mothlight.ai/api/v1/credentials/blocklist' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/credentials/blocklist",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/credentials/blocklist", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · Sanitized blocklist

Field	Type	Description
`generated_at`	`string`	—
`entries`	`object[]`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/credentials/range/{prefix}`

Professional or Enterprise

Credential hash range

Professional or Enterprise key required. Send only the first five SHA-1 hex characters; never send a password or full hash. Returns qualified sanitized broad-tier dictionary entries as SHA-1 suffix:source-count:attempt-count:last-seen-date lines. Empty matches return an empty body. This is attacker-dictionary evidence, not a general breach search; no match means unknown.

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key requests and returned hash lines count toward daily request and row quotas.

Parameters

Name	Location / type	Details
`prefix` (required)	path · string	Exactly five SHA-1 hexadecimal characters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/credentials/range/ABCDE' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/credentials/range/ABCDE",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/credentials/range/ABCDE", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · text/plain · One SHA-1 suffix:source-count:attempt-count:YYYY-MM-DD per line; empty when no matches.

Example response from the contract

(empty body)

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/credentials/usernames`

Professional or Enterprise

Targeted usernames

Professional or Enterprise key required. Sanitized usernames targeted in the last 30 days, ordered by sources then attempts. Emails, domain-like values and unsafe identifiers are excluded. Absence means unknown.

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`protocol`	query · string	Optional protocol, normalized to lowercase.
`limit`	query · integer	Maximum entries. Default: 200. Minimum: 1. Maximum: 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/credentials/usernames' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/credentials/usernames",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/credentials/usernames", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`username`	`string`	—
`attempts`	`integer`	—
`sources`	`integer`	—
`protocols`	`string[]`	—
`last_seen`	`string`	—

Example response from the contract

[]

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

Lookup

GET

`/api/v1/lookup/ip/{ip}`

Professional or Enterprise

Observed hostile activity for an IP

Brand hosts only. Professional or Enterprise bearer key with events scope required. One request and one row are metered. History is capped at 30 days and the plan delay applies. Absence is unknown, not safe. Details use at most 5000 newest events; totals cover the full window. No payloads, credentials, sensor names or other source IPs are returned. ASN results describe network activity, not the behavior of every member address.

Authentication: Authorization: Bearer YOUR_API_KEY. One request and one row per successful lookup.

Parameters

Name	Location / type	Details
`ip` (required)	path · string	Public IPv4 or IPv6 address; private and reserved ranges are rejected.

Example requests

curl

curl 'https://mothlight.ai/api/v1/lookup/ip/8.8.8.8' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/lookup/ip/8.8.8.8",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/lookup/ip/8.8.8.8", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · Evidence, confidence, action and limitations; ASN includes distinct_ips and active_day_share.

Field	Type	Description
`query`	`object`	—
`seen`	`boolean`	—
`verdict`	`object`	—
`first_seen`	`string \| null`	—
`last_seen`	`string \| null`	—
`events`	`integer`	—
`daily_counts`	`object[]`	—
`window`	`object`	UTC since/until timestamps and plan delay_minutes.
`evidence_classes`	`string[]`	—
`confidence`	`integer`	—
`suggested_action`	`object`	—
`action_reason`	`string`	—
`caveats`	`string[]`	—
`regions`	`object[]`	—
`protocols`	`object[]`	—
`categories`	`object[]`	—
`actors`	`object[]`	—
`signatures`	`string[]`	—
`techniques`	`string[]`	—
`cves`	`object[]`	—
`credential_activity`	`object`	Attempt count, modes and campaign ids only; no credential values.
`distinct_ips`	`integer`	ASN only; no member addresses returned.
`active_day_share`	`number`	—

Error codes

400 Invalid or reserved input.
401 Missing or invalid bearer key.
403 Paid plan and events scope required.
404 Non-brand host.
429 Rate or daily quota exceeded.

GET

`/api/v1/lookup/asn/{asn}`

Professional or Enterprise

Observed hostile activity for an ASN

Authentication: Authorization: Bearer YOUR_API_KEY. One request and one row per successful lookup.

Parameters

Name	Location / type	Details
`asn` (required)	path · string	ASN with optional AS prefix (1–4294967295).

Example requests

curl

curl 'https://mothlight.ai/api/v1/lookup/asn/AS13335' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/lookup/asn/AS13335",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/lookup/asn/AS13335", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · Evidence, confidence, action and limitations; ASN includes distinct_ips and active_day_share.

Field	Type	Description
`query`	`object`	—
`seen`	`boolean`	—
`verdict`	`object`	—
`first_seen`	`string \| null`	—
`last_seen`	`string \| null`	—
`events`	`integer`	—
`daily_counts`	`object[]`	—
`window`	`object`	UTC since/until timestamps and plan delay_minutes.
`evidence_classes`	`string[]`	—
`confidence`	`integer`	—
`suggested_action`	`object`	—
`action_reason`	`string`	—
`caveats`	`string[]`	—
`regions`	`object[]`	—
`protocols`	`object[]`	—
`categories`	`object[]`	—
`actors`	`object[]`	—
`signatures`	`string[]`	—
`techniques`	`string[]`	—
`cves`	`object[]`	—
`credential_activity`	`object`	Attempt count, modes and campaign ids only; no credential values.
`distinct_ips`	`integer`	ASN only; no member addresses returned.
`active_day_share`	`number`	—

Error codes

400 Invalid or reserved input.
401 Missing or invalid bearer key.
403 Paid plan and events scope required.
404 Non-brand host.
429 Rate or daily quota exceeded.

Feeds

GET

`/api/v1/export`

Researcher sample; Enterprise full export; raw by contract

CC BY sample (approved key) or scoped proprietary export

Approved bearer key required. Without export/raw scope: CC BY 4.0 sample of at most 500 rows per call, seven-day window, at least 60 minutes old, and 2,000 sample rows per UTC day. Includes synthetic provenance watermarks, not observed attacks. Enterprise export scope: proprietary JSON/CSV/NDJSON up to 50,000 rows per call and 20 calls per UTC day, subject to plan delay/history and daily rows. format=jsonl requires manually contracted raw scope and uses the payload/training schema. Query parameters never grant scope. All exports are no-store.

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key requests; sample rows or full-export rows and daily export calls are metered.

Parameters

Name	Location / type	Details
`format`	query · string	jsonl selects the raw-only payload/training schema. Allowed: ndjson, json, csv, jsonl. Default: ndjson.
`full`	query · string	Explicit full-export request; requires export or raw. Allowed: 1.
`scope`	query · string	Raw request; requires raw scope on the key. Use format=jsonl for training rows. Allowed: raw.
`raw`	query · string	Raw-request alias; requires raw scope on the key. Allowed: 1.
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`category`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`region`	query · string

Example requests

curl

curl 'https://mothlight.ai/api/v1/export' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/export",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/export", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · CC BY 4.0 sample (approved key) or proprietary full/training export, depending on key scopes and format.

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/feeds/edl`

Professional or Enterprise

Short-lived firewall IP external dynamic list

Brand host only. Organization-bound Professional/Enterprise events key and current organization entitlement required. Applies per-org allowlist; excludes verified/known services and reserved IPs. Shared infrastructure is observe-only unless exploit-backed. Window starts now minus 24h and ends at plan delay; expiry is last_seen plus 24h. Maximum 10000 IPs ordered by confidence then last_seen descending. Metered requests/rows, private/no-store. Generation failure permits last good selection for at most 15 minutes with live safety exclusions and expiry reapplied; otherwise empty success, X-EDL-Status empty-on-error. Configure appliances to replace on empty success; disable and clear appliance cache to roll back. Query key auth is exclusive to this endpoint and exposes credentials to URL logs; prefer bearer headers or a dedicated revocable key.

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`format`	query · string	Allowed: txt, json. Default: txt.
`min_confidence`	query · integer	Default: 0. Minimum: 0. Maximum: 100.

Example requests

curl

curl 'https://mothlight.ai/api/v1/feeds/edl' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/feeds/edl",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/feeds/edl", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · IPs or metadata; may be empty on generation failure

Field	Type	Description
`generated_at`	`string`	—
`criteria_version`	`string`	—
`degraded`	`boolean`	—
`window`	`object`	—
`entries`	`object[]`	—

Error codes

400 Invalid format or confidence
401 Missing or invalid key
403 Insufficient scope
404 Non-brand host
429 Request or row quota exceeded

Reports

GET

`/api/v1/reports`

Public; optional approved key

Published daily/weekly reports

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/reports'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/reports",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/reports", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`day`	`string`	—
`title`	`string`	—
`url`	`string`	—
`summary`	`object`	—

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

Access

POST

`/api/v1/access-requests`

Public access request form

Request API access (public form; key issued only after human approval)

Authentication: no key required.

Parameters

No parameters.

JSON request body

Field	Type	Description
`name`	`string`	—
`email`	`string`	—
`organisation`	`string`	—
`intendedUse`	`string`	—
`requestedPlan`	`string`	—
`requestedTier`	`string`	legacy alias for requestedPlan
`termsAccepted`	`boolean`	—
`website`	`string`	honeypot, leave empty
`formToken`	`string`	—
`powNonce`	`string`	—

Example requests

curl

curl -X POST 'https://mothlight.ai/api/v1/access-requests' \
  -H 'Content-Type: application/json' \
  --data '{"name":"YOUR_NAME","email":"YOUR_EMAIL","organisation":"YOUR_ORGANISATION","intendedUse":"YOUR_INTENDEDUSE","requestedPlan":"researcher","requestedTier":"YOUR_REQUESTEDTIER","termsAccepted":true,"website":"","formToken":"YOUR_FORMTOKEN","powNonce":"YOUR_POWNONCE"}'

Python

import requests
import json

response = requests.post(
    "https://mothlight.ai/api/v1/access-requests",
    headers={},
    json=json.loads('{"name":"YOUR_NAME","email":"YOUR_EMAIL","organisation":"YOUR_ORGANISATION","intendedUse":"YOUR_INTENDEDUSE","requestedPlan":"researcher","requestedTier":"YOUR_REQUESTEDTIER","termsAccepted":true,"website":"","formToken":"YOUR_FORMTOKEN","powNonce":"YOUR_POWNONCE"}'),
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/access-requests", {
  method: "POST",
  headers: {"Content-Type":"application/json"},
  body: JSON.stringify({"name":"YOUR_NAME","email":"YOUR_EMAIL","organisation":"YOUR_ORGANISATION","intendedUse":"YOUR_INTENDEDUSE","requestedPlan":"researcher","requestedTier":"YOUR_REQUESTEDTIER","termsAccepted":true,"website":"","formToken":"YOUR_FORMTOKEN","powNonce":"YOUR_POWNONCE"}),
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`ok`	`boolean`	—

Example response from the contract

{
  "ok": true
}

Error codes

400 Invalid parameter or public event pagination/window constraint.

Observatory /

The API, endpoint by endpoint.

Generated from the OpenAPI contract. Use an approved bearer key for gated data. Not seen means unknown, never safe.

Access & integration overview →Download OpenAPI →

Stats

GET

`/api/v1/stats/overview`

Public; optional approved key

Headline numbers for the index page

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/overview'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/overview",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/overview", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`updated_at`	`string`	—
`ai`	`object`	AI traffic measured honestly over the trailing 24h window. Web cells use HTTP(S) requests as the denominator; non-web service probes (SSH, Redis, ...) cannot be AI crawler requests and are reported separately. Verification tiers are event-local snapshots and are never reconstructed backwards.
`totals`	`object`	—
`last_24h`	`object`	—
`by_category_24h`	`object[]`	—
`top_bots_24h`	`object[]`	—
`regions`	`object[]`	—

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stats/credentials`

Public; optional approved key

Planned — delayed aggregate credential-attack intelligence

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`window`	query · string	Allowed: 7d, 30d. Default: 7d.

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/credentials'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/credentials",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/credentials", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`breach_reuse`	`object`	Counts only for the same completed-UTC-day window. overall and each by_protocol metric have status published or withheld. Published metrics include checked_groups (distinct observed password groups with a stored breach check), seen_groups (checked groups with seen=true), share (seen_groups/checked_groups), attempts_share (all credential attempts whose group is seen divided by all credential attempts), and checked_at_latest (latest stored check timestamp). Withheld metrics contain only status; requires at least 50 checked groups, 100 attempts and 20 source networks. Small protocol cells are omitted. No passwords, usernames, hashes or lookup material are included in this field.
`generated_at`	`string`	—
`window`	`object`	—
`delay_hours`	`integer`	—
`thresholds`	`object`	—
`totals`	`object`	—
`by_protocol`	`object[]`	—
`modes`	`object[]`	—
`modes_by_protocol`	`object[]`	Each split requires the cell threshold; share is of all attempts within that protocol. Omitted cells increment withheld.cells.
`ai_tooling`	`object`	—
`top_usernames`	`object[]`	—
`top_passwords`	`object[]`	—
`other_password_share`	`number`	—
`daily`	`object[]`	—
`withheld`	`object`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
404 Publication disabled
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stats/timeseries`

Public; optional approved key

Time series for a metric

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`metric` (required)	query · string	Allowed: events, unique_ips, ai_share, canary_hits, honeytoken_uses.
`interval`	query · string	Allowed: 1h, 1d. Default: 1h.
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`category`	query · string
`region`	query · string
`bot_id`	query · string

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/timeseries'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/timeseries",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/timeseries", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`metric`	`string`	—
`interval`	`string`	—
`since`	`string`	—
`until`	`string`	—
`points`	`object[]`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stats/top`

Public; optional approved key

Top-N breakdown

Public output contains at most 10 entries; aggregate cells below 3 events or 2 distinct sources are suppressed.

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`by` (required)	query · string	Allowed: path, ip, asn, country, bot, trap, ua, cve, persona, region.
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`category`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`region`	query · string
`limit`	query · integer	Default: 10. Maximum: 100.

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/top'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/top",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/top", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`by`	`string`	—
`since`	`string`	—
`items`	`object[]`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/regions`

Public; optional approved key

Sensor/region status and volume

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/regions'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/regions",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/regions", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`sensor_id`	`string`	—
`region`	`string`	—
`provider`	`string \| null`	—
`kind`	`string`	—
`hostname`	`string \| null`	—
`enabled`	`boolean`	—
`last_heartbeat`	`string \| null`	—
`healthy`	`boolean`	—
`events_24h`	`integer`	—
`events_total`	`integer`	—

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/honeytokens/stats`

Public; optional approved key

Honeytoken planting vs use, harvest-to-use latency

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.

Example requests

curl

curl 'https://mothlight.ai/api/v1/honeytokens/stats'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/honeytokens/stats",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/honeytokens/stats", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`planted`	`integer`	—
`used`	`integer`	—
`median_latency_sec`	`number \| null`	—
`by_placement`	`object[]`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stats/pulse`

Public; optional approved key

Live aggregate pulse

Last-hour aggregates with previous-hour comparison. Source-sensitive cells may be withheld. No event rows are returned. Anonymous responses are cached for 30 seconds.

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/pulse'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/pulse",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/pulse", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`window`	`object`	—
`updatedAt`	`string`	—
`minutes`	`object[]`	—
`totals`	`object`	—
`topCountries`	`object[]`	—
`withheldCountries`	`integer`	—
`map`	`object`	Country-level flow aggregates, with suppressed bucket/event and withheld-flow counts.

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stats/sample`

Public; optional approved key

Public sample and weekly dataset

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/sample'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/sample",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/sample", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`sample`	`object`	—
`dataset`	`object`	—

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stats/unknown`

Public; optional approved key

Unknown traffic explained

Delayed 24-hour aggregate explanation of traffic without a verified known identity. Withheld cells are null, never zero. Behavioral labels are inference, not operator attribution.

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/stats/unknown'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stats/unknown",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stats/unknown", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`updated_at`	`string`	—
`window`	`object`	—
`totals`	`object`	—
`by_family`	`object[]`	—
`by_protocol`	`object[]`	—
`by_stage`	`object[]`	—
`top_clusters`	`object[]`	—
`networks`	`object \| null`	—
`withheld`	`object`	—
`methodology_version`	`string`	—

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

Bots

GET

`/api/v1/bots`

Public; optional approved key

Leaderboard of labelled actors

Anonymous/read pages allow 50 rows with a 200-row cursor boundary. Gated event scopes allow 200-row pages. Public aggregate cells below 3 events or 2 distinct sources are suppressed.

Authentication: Authorization: Bearer YOUR_API_KEY. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`category`	query · string
`region`	query · string
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`q`	query · string	search in name/code/codename
`sort`	query · string	Allowed: events, last_seen, ai, confidence. Default: events.
`limit`	query · integer	Maximum 200 rows per page for events-scope callers; read scope cannot retrieve event rows. Default: 50. Minimum: 1. Maximum: 200.
`cursor`	query · string	Opaque next_cursor; public event offsets cannot reach or exceed 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/bots' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/bots",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/bots", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`items`	`object[]`	—
`next_cursor`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/bots/{bot_id}`

Public; optional approved key

Bot profile with public or scoped metadata

Public/read profiles omit signal weights, signal detail and internal notes. Gated event scopes (events, stream, export or raw) unlock those fields, subject to read-model redaction.

Authentication: Authorization: Bearer YOUR_API_KEY. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`bot_id` (required)	path · string	stable id (openai-gptbot

Example requests

curl

curl 'https://mothlight.ai/api/v1/bots/YOUR_BOT_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/bots/YOUR_BOT_ID",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/bots/YOUR_BOT_ID", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`id`	`string`	—
`code`	`string`	—
`codename`	`string \| null`	—
`name`	`string`	—
`vendor`	`string \| null`	—
`category`	`string`	—
`confidence`	`integer`	—
`ai_likelihood`	`integer`	—
`verification`	`string`	—
`events_24h`	`integer \| null`	Null = withheld by the publication rule (fewer than 3 events or fewer than 2 distinct sources), never zero.
`events_total`	`integer \| null`	Null = withheld by the publication rule, never zero.
`ip_count`	`integer \| null`	Null = withheld by the publication rule, never zero.
`counts_suppressed`	`boolean`	True when headline counts are withheld, typically for single-source actors.
`volume_band`	`string \| null`	Coarse non-identifying volume band for suppressed actors (e.g. 1k–10k requests); null when counts are publishable.
`first_seen`	`string`	—
`last_seen`	`string`	—
`countries`	`string[]`	—
`robots_compliance`	`number \| null`	—
`signals`	`object[]`	—
`top_paths`	`object[]`	—
`personas`	`string[]`	—
`regions`	`string[]`	—
`cves`	`string[]`	—
`canary_follows`	`integer \| null`	Null = below publication threshold, never a fabricated zero.
`honeytoken_uses`	`integer \| null`	Null = below publication threshold, never a fabricated zero.
`evidence_tiers`	`object[]`	—
`known_bot`	`object \| null`	—
`notes`	`string \| null`	Omitted for anonymous/read profiles.

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/bots/{bot_id}/events`

Professional or Enterprise

Events for a bot

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`bot_id` (required)	path · string
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`category`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`region`	query · string
`limit`	query · integer	Maximum 200 rows per page for events-scope callers; read scope cannot retrieve event rows. Default: 50. Minimum: 1. Maximum: 200.
`cursor`	query · string	Opaque next_cursor; public event offsets cannot reach or exceed 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/bots/YOUR_BOT_ID/events' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/bots/YOUR_BOT_ID/events",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/bots/YOUR_BOT_ID/events", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`items`	`object[]`	—
`next_cursor`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/bots/{bot_id}/timeseries`

Public; optional approved key

Activity time series for a bot

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`bot_id` (required)	path · string
`interval`	query · string	Allowed: 1h, 1d. Default: 1d.
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.

Example requests

curl

curl 'https://mothlight.ai/api/v1/bots/YOUR_BOT_ID/timeseries'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/bots/YOUR_BOT_ID/timeseries",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/bots/YOUR_BOT_ID/timeseries", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`metric`	`string`	—
`interval`	`string`	—
`since`	`string`	—
`until`	`string`	—
`points`	`object[]`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/robots-compliance`

Public; optional approved key

robots.txt compliance per bot

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`category`	query · string

Example requests

curl

curl 'https://mothlight.ai/api/v1/robots-compliance'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/robots-compliance",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/robots-compliance", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`bot_id`	`string`	—
`code`	`string`	—
`name`	`string`	—
`vendor`	`string \| null`	—
`category`	`string`	—
`verification`	`string`	—
`rules_tested`	`integer`	—
`violations`	`integer`	—
`compliance`	`number`	—
`last_violation_at`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/known-bots`

Public; optional approved key

Curated registry of known bots (UA tokens, vendor, verification method)

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/known-bots'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/known-bots",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/known-bots", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`slug`	`string`	—
`name`	`string`	—
`vendor`	`string`	—
`category`	`string`	—
`robots_token`	`string \| null`	—
`verification_method`	`string`	—
`docs_url`	`string \| null`	—
`purpose`	`string \| null`	—

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

Events

GET

`/api/v1/events`

Professional or Enterprise

Event list

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`category`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`region`	query · string
`trap`	query · string
`tag`	query · string
`ip`	query · string	Exact IP filter for events-scope callers.
`limit`	query · integer	Maximum 200 rows per page for events-scope callers; read scope cannot retrieve event rows. Default: 50. Minimum: 1. Maximum: 200.
`cursor`	query · string	Opaque next_cursor; public event offsets cannot reach or exceed 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/events' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/events",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/events", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`items`	`object[]`	—
`next_cursor`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/events/recent`

Professional or Enterprise

Recent events (alias of /events)

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`category`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`region`	query · string
`trap`	query · string
`tag`	query · string
`ip`	query · string	Exact IP filter for events-scope callers.
`limit`	query · integer	Maximum 200 rows per page for events-scope callers; read scope cannot retrieve event rows. Default: 50. Minimum: 1. Maximum: 200.
`cursor`	query · string	Opaque next_cursor; public event offsets cannot reach or exceed 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/events/recent' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/events/recent",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/events/recent", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`items`	`object[]`	—
`next_cursor`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/events/{event_id}`

Professional or Enterprise

Event detail

Authentication: Authorization: Bearer YOUR_API_KEY. One request counts toward the daily request quota. No event-list row debit.

Parameters

Name	Location / type	Details
`event_id` (required)	path · string

Example requests

curl

curl 'https://mothlight.ai/api/v1/events/YOUR_EVENT_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/events/YOUR_EVENT_ID",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/events/YOUR_EVENT_ID", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`id`	`string`	—
`ts`	`string`	—
`sensor`	`string`	—
`region`	`string \| null`	—
`persona`	`string \| null`	—
`proto`	`string`	—
`method`	`string \| null`	—
`path`	`string \| null`	—
`src_ip`	`string`	Public defaults mask non-vendors; verified AIC/AIA/SEC/MON vendors may be disclosed. Gated event scopes receive full IPs.
`country`	`string \| null`	—
`asn`	`integer \| null`	—
`as_org`	`string \| null`	—
`ua`	`string \| null`	—
`bot_id`	`string \| null`	—
`bot_code`	`string \| null`	—
`category`	`string`	—
`confidence`	`integer`	—
`ai_likelihood`	`integer`	—
`tags`	`string[]`	—
`trap_id`	`string \| null`	—
`response_status`	`integer \| null`	—
`credential_mode`	`string \| null`	Professional+ offline classification; null when no credential attempt was classified.
`credential_campaign`	`object \| null`	—
`payload_summary`	`object \| null`	Gated only; redacted payload summary rather than full private bytes.
`query`	`string \| null`	—
`headers`	`object \| null`	—
`body_sample`	`string \| null`	—
`body_sha256`	`string \| null`	—
`body_size`	`integer \| null`	—
`signals`	`object[]`	—
`cve_ids`	`string[]`	—
`ja4`	`string \| null`	—
`geo`	`object \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/stream`

Researcher aggregate; Professional or Enterprise per-event

Aggregate SSE (approved key) or scoped per-event SSE

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quota and connection rate limit; per-event access checks daily row allowance.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`Last-Event-ID`	header · string	Optional gated event ID to suppress on reconnect.
`category`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`region`	query · string

Example requests

curl

curl 'https://mothlight.ai/api/v1/stream' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/stream",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/stream", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · text/event-stream · SSE stream

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/canaries`

Professional or Enterprise

Canary trigger rows

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`category`	query · string
`region`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`limit`	query · integer	Maximum 200 rows per page for events-scope callers; read scope cannot retrieve event rows. Default: 50. Minimum: 1. Maximum: 200.
`cursor`	query · string	Opaque next_cursor; public event offsets cannot reach or exceed 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/canaries' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/canaries",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/canaries", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`items`	`object[]`	—
`next_cursor`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/prompts`

Professional or Enterprise

Redacted prompt captures

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`category`	query · string
`region`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`limit`	query · integer	Maximum 200 rows per page for events-scope callers; read scope cannot retrieve event rows. Default: 50. Minimum: 1. Maximum: 200.
`cursor`	query · string	Opaque next_cursor; public event offsets cannot reach or exceed 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/prompts' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/prompts",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/prompts", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`items`	`object[]`	—
`next_cursor`	`string \| null`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

Credentials

GET

`/api/v1/credentials/blocklist`

Professional or Enterprise

Sanitized attacker-dictionary blocklist (professional+)

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`format`	query · string	Output format. Allowed: txt, json, entra. Default: json.
`confidence`	query · string	Feed confidence tier. Allowed: broad, high. Default: broad.
`leaked`	query · string	Include only entries confirmed in breach corpora. Allowed: only.
`sort`	query · string	Priority places confirmed leaked entries first, then sources and attempts. Allowed: sources, priority. Default: sources.

Example requests

curl

curl 'https://mothlight.ai/api/v1/credentials/blocklist' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/credentials/blocklist",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/credentials/blocklist", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · Sanitized blocklist

Field	Type	Description
`generated_at`	`string`	—
`entries`	`object[]`	—

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/credentials/range/{prefix}`

Professional or Enterprise

Credential hash range

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key requests and returned hash lines count toward daily request and row quotas.

Parameters

Name	Location / type	Details
`prefix` (required)	path · string	Exactly five SHA-1 hexadecimal characters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/credentials/range/ABCDE' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/credentials/range/ABCDE",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/credentials/range/ABCDE", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · text/plain · One SHA-1 suffix:source-count:attempt-count:YYYY-MM-DD per line; empty when no matches.

Example response from the contract

(empty body)

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/credentials/usernames`

Professional or Enterprise

Targeted usernames

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`protocol`	query · string	Optional protocol, normalized to lowercase.
`limit`	query · integer	Maximum entries. Default: 200. Minimum: 1. Maximum: 200.

Example requests

curl

curl 'https://mothlight.ai/api/v1/credentials/usernames' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/credentials/usernames",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/credentials/usernames", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`username`	`string`	—
`attempts`	`integer`	—
`sources`	`integer`	—
`protocols`	`string[]`	—
`last_seen`	`string`	—

Example response from the contract

[]

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
404 not found
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

Lookup

GET

`/api/v1/lookup/ip/{ip}`

Professional or Enterprise

Observed hostile activity for an IP

Authentication: Authorization: Bearer YOUR_API_KEY. One request and one row per successful lookup.

Parameters

Name	Location / type	Details
`ip` (required)	path · string	Public IPv4 or IPv6 address; private and reserved ranges are rejected.

Example requests

curl

curl 'https://mothlight.ai/api/v1/lookup/ip/8.8.8.8' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/lookup/ip/8.8.8.8",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/lookup/ip/8.8.8.8", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · Evidence, confidence, action and limitations; ASN includes distinct_ips and active_day_share.

Field	Type	Description
`query`	`object`	—
`seen`	`boolean`	—
`verdict`	`object`	—
`first_seen`	`string \| null`	—
`last_seen`	`string \| null`	—
`events`	`integer`	—
`daily_counts`	`object[]`	—
`window`	`object`	UTC since/until timestamps and plan delay_minutes.
`evidence_classes`	`string[]`	—
`confidence`	`integer`	—
`suggested_action`	`object`	—
`action_reason`	`string`	—
`caveats`	`string[]`	—
`regions`	`object[]`	—
`protocols`	`object[]`	—
`categories`	`object[]`	—
`actors`	`object[]`	—
`signatures`	`string[]`	—
`techniques`	`string[]`	—
`cves`	`object[]`	—
`credential_activity`	`object`	Attempt count, modes and campaign ids only; no credential values.
`distinct_ips`	`integer`	ASN only; no member addresses returned.
`active_day_share`	`number`	—

Error codes

400 Invalid or reserved input.
401 Missing or invalid bearer key.
403 Paid plan and events scope required.
404 Non-brand host.
429 Rate or daily quota exceeded.

GET

`/api/v1/lookup/asn/{asn}`

Professional or Enterprise

Observed hostile activity for an ASN

Authentication: Authorization: Bearer YOUR_API_KEY. One request and one row per successful lookup.

Parameters

Name	Location / type	Details
`asn` (required)	path · string	ASN with optional AS prefix (1–4294967295).

Example requests

curl

curl 'https://mothlight.ai/api/v1/lookup/asn/AS13335' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/lookup/asn/AS13335",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/lookup/asn/AS13335", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · Evidence, confidence, action and limitations; ASN includes distinct_ips and active_day_share.

Field	Type	Description
`query`	`object`	—
`seen`	`boolean`	—
`verdict`	`object`	—
`first_seen`	`string \| null`	—
`last_seen`	`string \| null`	—
`events`	`integer`	—
`daily_counts`	`object[]`	—
`window`	`object`	UTC since/until timestamps and plan delay_minutes.
`evidence_classes`	`string[]`	—
`confidence`	`integer`	—
`suggested_action`	`object`	—
`action_reason`	`string`	—
`caveats`	`string[]`	—
`regions`	`object[]`	—
`protocols`	`object[]`	—
`categories`	`object[]`	—
`actors`	`object[]`	—
`signatures`	`string[]`	—
`techniques`	`string[]`	—
`cves`	`object[]`	—
`credential_activity`	`object`	Attempt count, modes and campaign ids only; no credential values.
`distinct_ips`	`integer`	ASN only; no member addresses returned.
`active_day_share`	`number`	—

Error codes

400 Invalid or reserved input.
401 Missing or invalid bearer key.
403 Paid plan and events scope required.
404 Non-brand host.
429 Rate or daily quota exceeded.

Feeds

GET

`/api/v1/export`

Researcher sample; Enterprise full export; raw by contract

CC BY sample (approved key) or scoped proprietary export

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key requests; sample rows or full-export rows and daily export calls are metered.

Parameters

Name	Location / type	Details
`format`	query · string	jsonl selects the raw-only payload/training schema. Allowed: ndjson, json, csv, jsonl. Default: ndjson.
`full`	query · string	Explicit full-export request; requires export or raw. Allowed: 1.
`scope`	query · string	Raw request; requires raw scope on the key. Use format=jsonl for training rows. Allowed: raw.
`raw`	query · string	Raw-request alias; requires raw scope on the key. Allowed: 1.
`since`	query · string	Window start; event lists clamp to the plan history. Registered samples allow a seven-day window.
`until`	query · string	Window end; event lists clamp to the plan delay. Registered samples are at least 60 minutes old.
`category`	query · string
`persona`	query · string	Allowed: generic, saas, devops, ailab, blog.
`region`	query · string

Example requests

curl

curl 'https://mothlight.ai/api/v1/export' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/export",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/export", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · CC BY 4.0 sample (approved key) or proprietary full/training export, depending on key scopes and format.

Error codes

400 Invalid parameter or public event pagination/window constraint.
401 unauthorized
403 Required scope missing; contact help@mothlight.ai for access.
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

GET

`/api/v1/feeds/edl`

Professional or Enterprise

Short-lived firewall IP external dynamic list

Authentication: Authorization: Bearer YOUR_API_KEY. Per-key request quotas; returned entries count toward daily row quota.

Parameters

Name	Location / type	Details
`format`	query · string	Allowed: txt, json. Default: txt.
`min_confidence`	query · integer	Default: 0. Minimum: 0. Maximum: 100.

Example requests

curl

curl 'https://mothlight.ai/api/v1/feeds/edl' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/feeds/edl",
    headers={"Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/feeds/edl", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_API_KEY"},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · IPs or metadata; may be empty on generation failure

Field	Type	Description
`generated_at`	`string`	—
`criteria_version`	`string`	—
`degraded`	`boolean`	—
`window`	`object`	—
`entries`	`object[]`	—

Error codes

400 Invalid format or confidence
401 Missing or invalid key
403 Insufficient scope
404 Non-brand host
429 Request or row quota exceeded

Reports

GET

`/api/v1/reports`

Public; optional approved key

Published daily/weekly reports

Authentication: no key required. Anonymous rate limit; approved keys count toward per-key daily request quota.

Parameters

No parameters.

Example requests

curl

curl 'https://mothlight.ai/api/v1/reports'

Python

import requests

response = requests.get(
    "https://mothlight.ai/api/v1/reports",
    headers={},
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/reports", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`day`	`string`	—
`title`	`string`	—
`url`	`string`	—
`summary`	`object`	—

Error codes

401 unauthorized
429 Minute ceiling or daily quota exceeded. Counters are per runtime.

Access

POST

`/api/v1/access-requests`

Public access request form

Request API access (public form; key issued only after human approval)

Authentication: no key required.

Parameters

No parameters.

JSON request body

Field	Type	Description
`name`	`string`	—
`email`	`string`	—
`organisation`	`string`	—
`intendedUse`	`string`	—
`requestedPlan`	`string`	—
`requestedTier`	`string`	legacy alias for requestedPlan
`termsAccepted`	`boolean`	—
`website`	`string`	honeypot, leave empty
`formToken`	`string`	—
`powNonce`	`string`	—

Example requests

curl

curl -X POST 'https://mothlight.ai/api/v1/access-requests' \
  -H 'Content-Type: application/json' \
  --data '{"name":"YOUR_NAME","email":"YOUR_EMAIL","organisation":"YOUR_ORGANISATION","intendedUse":"YOUR_INTENDEDUSE","requestedPlan":"researcher","requestedTier":"YOUR_REQUESTEDTIER","termsAccepted":true,"website":"","formToken":"YOUR_FORMTOKEN","powNonce":"YOUR_POWNONCE"}'

Python

import requests
import json

response = requests.post(
    "https://mothlight.ai/api/v1/access-requests",
    headers={},
    json=json.loads('{"name":"YOUR_NAME","email":"YOUR_EMAIL","organisation":"YOUR_ORGANISATION","intendedUse":"YOUR_INTENDEDUSE","requestedPlan":"researcher","requestedTier":"YOUR_REQUESTEDTIER","termsAccepted":true,"website":"","formToken":"YOUR_FORMTOKEN","powNonce":"YOUR_POWNONCE"}'),
    timeout=30,
)
response.raise_for_status()
print(response.text)

JavaScript

const response = await fetch("https://mothlight.ai/api/v1/access-requests", {
  method: "POST",
  headers: {"Content-Type":"application/json"},
  body: JSON.stringify({"name":"YOUR_NAME","email":"YOUR_EMAIL","organisation":"YOUR_ORGANISATION","intendedUse":"YOUR_INTENDEDUSE","requestedPlan":"researcher","requestedTier":"YOUR_REQUESTEDTIER","termsAccepted":true,"website":"","formToken":"YOUR_FORMTOKEN","powNonce":"YOUR_POWNONCE"}),
});
if (!response.ok) throw new Error(String(response.status));
console.log(await response.text());

Response fields

200 · application/json · OK

Field	Type	Description
`ok`	`boolean`	—

Example response from the contract

{
  "ok": true
}

Error codes

400 Invalid parameter or public event pagination/window constraint.