API documentation · 3 of 9

Quick start

A whole audit from a terminal: create a project, set it up, crawl it, and read what it found. You need a key with write and, for the polling loop, jq.

With curl

# Your key, from Account → API keys, with write ticked
API=http://localhost:9000/api/v1
KEY=sk_live_...

# 1. Create the project → 201, with its id
ID=$(curl -s -X POST "$API/projects" -H "Authorization: Bearer $KEY" \
  -d '{"url": "https://example.com"}' | jq .id)

# 2. Toggle settings → only the fields you send change
curl -s -X PATCH "$API/projects/$ID" -H "Authorization: Bearer $KEY" \
  -d '{"crawl_sitemap": true, "check_external_links": true}'

# 3. Start crawling → 202, the crawl runs in the background
curl -s -X POST "$API/projects/$ID/crawls" -H "Authorization: Bearer $KEY"

# 4. Wait for it; total_urls climbs while it runs
until [ "$(curl -s "$API/projects/$ID" -H "Authorization: Bearer $KEY" \
      | jq .last_crawl.crawling)" = "false" ]; do sleep 5; done

# 5. Fetch the results
curl -s "$API/projects/$ID/report" -H "Authorization: Bearer $KEY" | jq '.health, .top_issues'
curl -s "$API/projects/$ID/pages?page=1" -H "Authorization: Bearer $KEY"

With Python

import time, requests

API = "http://localhost:9000/api/v1"
auth = {"Authorization": "Bearer sk_live_..."}

project = requests.post(f"{API}/projects", headers=auth,
                        json={"url": "https://example.com"}).json()
pid = project["id"]

requests.patch(f"{API}/projects/{pid}", headers=auth, json={"crawl_sitemap": True})
requests.post(f"{API}/projects/{pid}/crawls", headers=auth)

while requests.get(f"{API}/projects/{pid}", headers=auth).json()["last_crawl"]["crawling"]:
    time.sleep(5)

report = requests.get(f"{API}/projects/{pid}/report", headers=auth).json()
print(report["health"]["score"], report["top_issues"][:5])

If the project already exists, step 1 answers 409 project_exists and its address is in the Location header. Use that id instead.