REST API v1
Start crawls, pull issues, approve fixes. Stay in the loop with webhooks.
All endpoints return JSON. To authenticate, create a key under Settings → API keys in the dashboard and add it to every request:
Authorization: Bearer sk_...| Method | Path | Description |
|---|---|---|
GET | /api/v1/projects/ | List projects |
POST | /api/v1/projects/ | Create a project (name, base_url) |
POST | /api/v1/projects/{id}/crawls/ | Start a crawl (202) |
GET | /api/v1/crawls/{id}/ | Crawl status, score, category scores |
GET | /api/v1/crawls/{id}/issues/?severity=high | Issues (paginated; severity, category, rule_id filters) |
GET | /api/v1/fixes/?project=1&status=proposed | Fixes |
PATCH | /api/v1/fixes/{id}/ | Edit with new_value (creates a new version) |
POST | /api/v1/fixes/{id}/approve/ | Publish · reject/ · revert/ |
GET | /api/v1/projects/{id}/delivery/ | All live fixes (to apply on your own infrastructure) |
Example: crawl and score check in CI
KEY=sk_...; API=https://balanseo.ai/api/v1
CRAWL=$(curl -s -X POST -H "Authorization: Bearer $KEY" $API/projects/1/crawls/ | jq .id)
until [ "$(curl -s -H "Authorization: Bearer $KEY" $API/crawls/$CRAWL/ | jq -r .status)" = done ]; do sleep 10; done
SCORE=$(curl -s -H "Authorization: Bearer $KEY" $API/crawls/$CRAWL/ | jq .score)
[ "$SCORE" -ge 80 ] || { echo "SEO skoru düştü: $SCORE"; exit 1; }Webhooks
Add an HTTPS URL in project settings. Events: crawl.finished, fix.approved, uptime.down, uptime.up. Slack, Discord and Telegram formats are also supported.
POST /senin-adresin
X-Balanseo-Event: crawl.finished
X-Balanseo-Signature: t=1760000000,v1=<hex hmac-sha256(secret, "t.body")>
{"event":"crawl.finished","data":{"project":1,"crawl_id":42,"score":87,"issues":{"total":31,"critical":0,"new":4}}}Verifying the signature (Python):
import hmac, hashlib
t, v1 = dict(p.split("=") for p in header.split(",")).values()
expected = hmac.new(secret.encode(), f"{t}.{body}".encode(), hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, v1)Delivery endpoints (public)
The pixel, Edge Worker and proxy use these endpoints. The identifier is the project's public key; only live fixes are returned.
GET /d/{public_key}/p.js JS pixel
GET /d/{public_key}/fixes?path=/x Sayfa düzeltmeleri
GET /d/{public_key}/site robots.txt, llms.txt, sitemap, başlıklar, yönlendirmeler
POST /d/{public_key}/beacon RUM metrikleri / bot ziyaretleri