REST API.

export SEOPRIMO_KEY="sp_live_..."
API=https://seoprimo.it/api/v1
AUTH="Authorization: Bearer $SEOPRIMO_KEY"

# 1. add the site (free). If it already exists the answer is 409: take its id from GET /sites
SITE_ID=$(curl -sS -X POST "$API/sites" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"url": "https://www.acmescarpe.it/", "name": "Acme Scarpe"}' | jq -r .id)

# 2. the price of the quick audit, without running it
curl -sS -X POST "$API/sites/$SITE_ID/audits?dry_run=true" -H "$AUTH"
# {"estimated_credits":10}

# 3. start the quick audit (answer 202: {"id": "...", "status": "queued", "cost": 10})
AUDIT_ID=$(curl -sS -X POST "$API/sites/$SITE_ID/audits" -H "$AUTH" | jq -r .id)

# 4. poll until the audit is done or failed
while true; do
  STATUS=$(curl -sS "$API/sites/$SITE_ID/audits" -H "$AUTH" \
    | jq -r --arg id "$AUDIT_ID" '.audits[] | select(.id == $id) | .status')
  echo "status: $STATUS"
  [ "$STATUS" = "done" ] || [ "$STATUS" = "failed" ] && break
  sleep 10
done

# 5. the SeoPrimo Score
curl -sS "$API/sites/$SITE_ID/score" -H "$AUTH" | jq '{score, preliminary, pillars}'

import os
import time

import httpx

api = httpx.Client(
    base_url="https://seoprimo.it/api/v1",
    headers={"Authorization": f"Bearer {os.environ['SEOPRIMO_KEY']}"},
    timeout=30,
)


def ok(response: httpx.Response) -> dict:
    if response.is_error:
        body = response.json()  # always {"error": code, "detail": ...}
        raise RuntimeError(f"{response.status_code} {body['error']}: {body['detail']}")
    return response.json()


# 1. add the site (free). If it already exists the answer is 409: take its id from GET /sites
site = ok(api.post("/sites", json={"url": "https://www.acmescarpe.it/", "name": "Acme Scarpe"}))
site_id = site["id"]

# 2. the price of the quick audit, without running it
print(ok(api.post(f"/sites/{site_id}/audits", params={"dry_run": "true"})))  # {'estimated_credits': 10}

# 3. start the quick audit (answer 202)
audit_id = ok(api.post(f"/sites/{site_id}/audits"))["id"]

# 4. poll until the audit is done or failed
while True:
    audits = ok(api.get(f"/sites/{site_id}/audits"))["audits"]
    audit = next(a for a in audits if a["id"] == audit_id)
    print("status:", audit["status"])
    if audit["status"] in ("done", "failed"):
        break
    time.sleep(10)

# 5. the SeoPrimo Score
score = ok(api.get(f"/sites/{site_id}/score"))
print(score["score"], "preliminary" if score["preliminary"] else "full", score["pillars"])

// Node 18+ (global fetch)
const API = "https://seoprimo.it/api/v1";
const headers = { Authorization: `Bearer ${process.env.SEOPRIMO_KEY}`, "Content-Type": "application/json" };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function call(method, path, body) {
  const response = await fetch(API + path, { method, headers, body: body && JSON.stringify(body) });
  const data = await response.json();
  if (!response.ok) throw new Error(`${response.status} ${data.error}: ${JSON.stringify(data.detail)}`);
  return data;
}

// 1. add the site (free). If it already exists the answer is 409: take its id from GET /sites
const site = await call("POST", "/sites", { url: "https://www.acmescarpe.it/", name: "Acme Scarpe" });

// 2. the price of the quick audit, without running it
console.log(await call("POST", `/sites/${site.id}/audits?dry_run=true`)); // { estimated_credits: 10 }

// 3. start the quick audit (answer 202)
const started = await call("POST", `/sites/${site.id}/audits`);

// 4. poll until the audit is done or failed
let audit;
do {
  await sleep(10_000);
  const { audits } = await call("GET", `/sites/${site.id}/audits`);
  audit = audits.find((a) => a.id === started.id);
  console.log("status:", audit.status);
} while (!["done", "failed"].includes(audit.status));

// 5. the SeoPrimo Score
const score = await call("GET", `/sites/${site.id}/score`);
console.log(score.score, score.preliminary ? "preliminary" : "full", score.pillars);