Developers
API reference
A REST API over everything Monitelia collects for your project — 33 data resources, scan triggers for 32 modules, and BI-ready exports. Every endpoint is authenticated with a project-scoped bearer token and returns JSON (or CSV where noted). Create and manage tokens in Project → Settings → API tokens. Machine-readable spec: /api/v1/openapi.json.
Authentication
Pass your token as a bearer header. Tokens start with seo_, are shown once at creation, and are stored only as a hash — if you lose one, revoke it and mint another. Requests are rate-limited to 60/minute per token.
curl https://monitelia.com/api/v1/mentions?limit=20 \ -H "Authorization: Bearer seo_your_token_here"
Scopes
A token only reaches the scopes you grant it at creation.
ai:read | AI visibility & AI Overview |
audience:read | Author profiles & audience |
audits:read | Site/app/accessibility audits |
backlinks:read | Backlinks & referring domains |
crawls:read | Read crawls & issues |
crawls:trigger | Start site crawls |
local:read | Google Business Profile reviews |
mentions:read | Mentions, digests, topics, visual insights |
narratives:read | Story clusters & actor groups |
notifications:read | Notification feed |
rankings:read | Keywords, rankings, Brand SERP |
scans:trigger | Trigger any module scan |
security:read | Email auth, DMARC, TLS/DNS posture, assets |
threats:read | Threat findings, cases, squats, abuse reports |
tm:read | Trademark filings |
uptime:read | Uptime monitors & incidents |
vip:read | VIP protection profiles |
watches:read | Watch snapshots |
work:read | Read the work ledger (scan outcomes) |
Data resources
Every resource follows one contract: GET /api/v1/{resource} with limit (1–500, default 50), offset, and format=json|csv. The response is { <resource>: rows[], total, limit, offset, next_offset }, newest first. Unknown filter params return 400 with the whitelist — a typo never silently returns unfiltered data.
/api/v1/mentionsmentions:readBrand/topic mentions across web, news, social, forums and review sites.
Filters: source · sentiment (positive|neutral|negative) · category · language · country
Columns: id, source, url, source_domain, outlet, outlet_reach, outlet_tier, subject_role, title, snippet, author, language, country, sentiment, category, tags, reach, posted_at, found_at
/api/v1/narrativesnarratives:readMentions clustered into stories, with coverage-gap and coordination signals.
Columns: id, headline, first_seen, last_seen, mention_count, outlet_count, total_reach, pct_negative, pct_neutral, pct_positive, coverage_gap, sync_minutes, similarity, coordination_score, coordination_flags, updated_at
/api/v1/actor-groupsnarratives:readRecurring account casts that co-appear across coordinated stories.
Columns: id, actors, cluster_ids, shared_stories, mention_count, first_seen, last_seen, computed_at
/api/v1/digestsmentions:readAI mention digests: themes, risks and advice over a time window.
Columns: id, window_days, computed_at, headline, summary, themes, advice, risks, mention_count, is_ai
/api/v1/topicsmentions:readMonitored subjects beyond the brand: topics, products, events, competitors.
Filters: kind
Columns: id, kind, query, label, active, window_start, window_end, created_at
/api/v1/author-profilesaudience:readProfiled authors behind the project's mentions.
Columns: id, author, source, mention_count, total_reach, profession, interests, topics, summary, profiled_at
/api/v1/visual-insightsmentions:readImage-level brand/logo appearances with scene analysis.
Columns: id, image_url, source_url, brand_present, logo_present, objects, scene, sentiment, summary, analyzed_at
/api/v1/brand-serprankings:readWhat Google shows for the brand name, position by position.
Columns: id, snapshot_date, position, url, domain, title, classification, is_negative_top5, created_at
/api/v1/threatsthreats:readThreat findings: phishing, impersonation, typosquats, fake pages, leaks.
Filters: severity (critical|high|medium|low) · threat_type · detector
Columns: id, threat_type, detector, platform, title, target_url, severity, threat_score, is_live_phishing, found_at
/api/v1/casesthreats:readEnforcement cases built from findings, with lifecycle status.
Filters: status · severity (critical|high|medium|low)
Columns: id, threat_type, status, severity, threat_score, title, target_url, platform, created_at, updated_at, closed_at
/api/v1/squatsthreats:readLookalike domains: typos, homoglyphs, bitflips, combos.
Filters: severity (critical|warning|info) · match_type
Columns: id, domain, match_type, similarity_score, severity, first_seen_at, registered_at, registrar, has_a_record, has_mx_record, urlscan_verdict, created_at
/api/v1/tm-filingstm:readTrademark filings conflicting with the brand across USPTO, EUIPO, WIPO, UA, CA.
Filters: registry · status
Columns: id, registry, application_no, mark, applicant, nice_classes, filed_at, status, status_date, conflict_score, url, found_at
/api/v1/abuse-reportsthreats:readAbuse reports filed to registrars/hosts, with delivery status.
Columns: id, url, channel, method, status, external_id, created_at
/api/v1/vipvip:readProtected people: executives, founders, public faces.
Columns: id, name, role, aliases, enabled, created_at
/api/v1/keywordsrankings:readTracked keywords (the ranking series lives under /api/v1/rankings).
Columns: id, keyword, country, language, device, search_engine, created_at
/api/v1/keyword-candidatesrankings:readKeyword opportunities discovered from the site's own pages.
Filters: status
Columns: id, term, score, page_count, example_url, status, created_at
/api/v1/backlinksbacklinks:readDiscovered backlinks with follow status and link health.
Filters: status · source_domain
Columns: id, source_url, source_domain, target_url, anchor, is_dofollow, rank, status, first_seen, last_seen, found_at
/api/v1/backlink-domainsbacklinks:readReferring domains aggregated, with domain rank.
Columns: id, domain, backlinks_count, domain_rank, first_seen, last_seen
/api/v1/ai-overviewai:readGoogle AI Overview presence and brand citations per keyword.
Columns: id, keyword, present, brand_cited, brand_position, cited_domains, snippet, checked_at
/api/v1/a11yaudits:readAccessibility (axe-core) scan scores per URL.
Columns: id, url, engine, score, total_violations, axe_version, scanned_at
/api/v1/a11y-issuesaudits:readIndividual WCAG violations from accessibility scans.
Filters: impact · rule_id
Columns: id, scan_id, rule_id, impact, wcag_criterion, help, help_url, nodes, sample_target, created_at
/api/v1/app-auditaudits:readApp-store listing audits (App Store / Google Play).
Columns: id, platform, app_id, title, category, current_version, version_released_at, rating_avg, rating_count, issues, checked_at
/api/v1/gbp-reviewslocal:readGoogle Business Profile reviews (needs a connected GBP).
Columns: id, reviewer, star_rating, comment, reply, reply_at, posted_at
/api/v1/email-authsecurity:readSPF/DKIM/DMARC/BIMI posture snapshots per sending domain.
Columns: id, checked_at, dmarc_record, dmarc_policy, dmarc_pct, spf_record, spf_lookup_count, spf_valid, dkim_found, bimi_record, mx_present, score, issues, recommendations
/api/v1/dmarc-reportssecurity:readAggregated DMARC (rua) reports: who sends as your domain, and does it pass.
Columns: id, org_name, report_begin, report_end, source_ip, source_country, message_count, spf_pass, dkim_pass, disposition, received_at
/api/v1/securitysecurity:readTLS/DNS security posture snapshots: certs, DNSSEC, blocklists.
Columns: id, domain, checked_at, ssl_issuer, ssl_not_after, ssl_days_left, ssl_valid, tls_version, dnssec, dnsbl_listed, dnsbl_clean, score, issues, recommendations
/api/v1/posture-diffssecurity:readWhat changed since the last posture snapshot: regressions and improvements.
Columns: id, computed_at, window_days, score_delta, regressions, improvements, unchanged, unmeasured
/api/v1/assetssecurity:readDiscovered asset inventory: domains, hosts, endpoints, accounts.
Filters: kind · monitored
Columns: id, kind, value, label, source, monitored, confidence, tags, first_seen, last_seen
/api/v1/uptime-monitorsuptime:readConfigured uptime monitors.
Columns: id, name, type, target, method, interval_minutes, enabled, created_at
/api/v1/uptime-incidentsuptime:readDowntime incidents with cause and resolution time.
Filters: status
Columns: id, monitor_id, started_at, resolved_at, status, cause
/api/v1/watch-snapshotswatches:readDaily rollups per Watch: finding counts by severity, channel summaries.
Columns: id, watch_id, snapshot_date, total_findings, critical_count, high_count, medium_count, channel_summaries, created_at
/api/v1/notificationsnotifications:readThe project's notification feed (same items as the in-app bell).
Filters: event_type · severity
Columns: id, event_type, severity, title, body, link, read_at, created_at
/api/v1/workwork:readThe work ledger: every dispatched scan with its status and outcome.
Filters: status · kind
Columns: id, kind, trigger, status, result_summary, error_code, error, started_at, finished_at
Actions & special endpoints
/api/v1/crawlscrawls:triggerStart a crawl for the token's project.
start_url— URL to crawl (required)max_pages— 1–50000, default 500render_js— boolean, default false
/api/v1/crawlscrawls:readList recent crawls and their status.
/api/v1/crawls/{id}crawls:readA single crawl with its issue summary.
/api/v1/rankingsrankings:readLatest rank per tracked keyword.
/api/v1/ai-visibilityai:readPer-prompt model answers (mention, tone, share of voice) + top cited domains.
/api/v1/scansscans:triggerList every scan module this API can dispatch.
/api/v1/scansscans:triggerTrigger a module scan; follow the outcome in /api/v1/work.
module— one of 32 modules — see GET /api/v1/scans
/api/v1/datasetvaries by tableFlat, wide table for BI tools (Power BI, Looker Studio, Metabase, Excel). One rectangular dataset, predictable paging, primitive columns.
table— mentions | threats | rankingsformat— json (default) | csvlimit— 1–5000, default 1000offset— page with next_offset until null
Scan modules
POST /api/v1/scans with { "module": "…" } dispatches any of these. Every dispatch lands in the work ledger — poll GET /api/v1/work to see it finish.
mentions-web | Web mentions (search engines, forums) |
mentions-social | Social mentions (Reddit, YouTube, Mastodon, Telegram…) |
mentions-news | News mentions (RSS + news search) |
mentions-reviews | Review-site mentions |
narratives | Cluster mentions into narratives; coordination signals |
visual-insights | Visual/logo appearances |
image-search | Google Images brand scan |
audience | Author/audience profiling over collected mentions |
brand-protection | Full brand-protection detector sweep |
typosquatting | Lookalike-domain scan |
marketplace | Marketplace listings scan |
secret-scan | Leaked-secret scan (public code/paste sites) |
threat-feeds | Threat-intel feed correlation |
phishing-verify | Re-verify live phishing findings |
tm-filings | Trademark-registry conflict scan (USPTO, EUIPO, WIPO, UA, CA) |
rankings | Keyword rank check across engines |
ai-overview | Google AI Overview presence |
ai-visibility | LLM answer visibility (share of voice) |
keyword-explorer | Keyword Explorer position sweep |
backlinks | Backlink discovery + health check |
local-seo | Local SEO (GBP) rankings sync |
app-audit | App-store listing audit |
aso-rankings | ASO keyword positions |
a11y | Accessibility (axe-core) check |
email-auth | SPF/DKIM/DMARC/MTA-STS posture |
security | DNS/TLS/security posture scan |
assets | Asset inventory discovery |
rdap-watch | RDAP watch of the project's own domains |
posture-diff | Posture change detection vs. last snapshot |
gsc-sync | Search Console data sync (needs a connected GSC) |
ga4-sync | GA4 data sync (needs a connected GA4) |
social-sync | Connected social accounts sync |
Connecting a BI tool
Every data resource speaks CSV (format=csv), and /api/v1/dataset serves the classic flat tables. Page by following next_offset until it comes back null.
# Power BI: Get Data → Web → Advanced → add a header # Authorization: Bearer seo_your_token_here https://monitelia.com/api/v1/dataset?table=mentions&limit=5000 # Or pull any resource as CSV straight into a spreadsheet: curl -H "Authorization: Bearer seo_your_token_here" \ "https://monitelia.com/api/v1/backlinks?format=csv&limit=500" > backlinks.csv
Responses & errors
Success returns 200 (or 202 for accepted scans) with a JSON body; list endpoints include total, limit, offset and next_offset. Errors return a JSON error string with an appropriate status: 400 (bad input — the body lists valid values), 401 (missing/invalid token), 403 (token lacks the scope), 404 (unknown resource), 429 (rate limit), 502 (scan dispatch failed).
Need an endpoint we don't list yet?
The API grows with the product. Tell us what you're building →