Developers

API reference

A REST API over your project data. Every endpoint is authenticated with a project-scoped bearer token and returns JSON. Create and manage tokens in Project → Settings → API tokens.

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.

`crawls:trigger`	Start crawls
`crawls:read`	Read crawls & issues
`rankings:read`	Read keyword rankings
`mentions:read`	Read brand mentions
`threats:read`	Read threat findings & cases
`ai:read`	Read AI-visibility data
`backlinks:read`	Read backlinks

Endpoints

POST/api/v1/crawlscrawls:trigger

Start a crawl for the token's project.

start_url — URL to crawl (required)
max_pages — 1–50000, default 500
render_js — boolean, default false

GET/api/v1/crawlscrawls:read

List recent crawls and their status.

GET/api/v1/crawls/{id}crawls:read

A single crawl with its issue summary.

GET/api/v1/rankingsrankings:read

Latest rank per tracked keyword.

GET/api/v1/mentionsmentions:read

Brand mentions, newest first.

limit — 1–200, default 50
offset — default 0
source — filter by source
sentiment — positive|neutral|negative

GET/api/v1/threatsthreats:read

Threat findings (default) or enforcement cases.

view — findings|cases, default findings
severity — critical|high|medium|low
status — cases only
limit — 1–200
offset — default 0

GET/api/v1/ai-visibilityai:read

Per-prompt model answers (mention, tone, share of voice) + top cited domains.

GET/api/v1/datasetvaries by table

Flat, wide table for BI tools (Power BI, Looker Studio, Metabase, Excel). One rectangular dataset, predictable paging, primitive columns.

table — mentions | threats | rankings
format — json (default) | csv
limit — 1–5000, default 1000
offset — page with next_offset until null

Connecting a BI tool

/api/v1/dataset returns one flat table with primitive columns — the shape Power BI, Looker Studio, Metabase and Excel Power Query expect. 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 CSV straight into a spreadsheet:
curl -H "Authorization: Bearer seo_your_token_here" \
  "https://monitelia.com/api/v1/dataset?table=mentions&format=csv" > mentions.csv

Tables: mentions (needs mentions:read), threats (threats:read), rankings (rankings:read).

Responses & errors

Success returns 200 with a JSON body; list endpoints include total, limit, and offset. Errors return a JSON error string with an appropriate status: 401 (missing/invalid token), 403 (token lacks the scope),404 (project not found), 429 (rate limit).

Need an endpoint we don't list yet?

The API grows with the product. Tell us what you're building →