API Examples

Ready-to-use code examples for common API operations. Examples are provided in curl, JavaScript, and Python.

List All Projects

``bash


curl
curl -X GET "https://seogeo.tools/api/public/v1/projects" \
-H "Authorization: Bearer sg_live_xxx"

javascript
// JavaScript
const response = await fetch("https://seogeo.tools/api/public/v1/projects", {
headers: { "Authorization": "Bearer sg_live_xxx" }
});
const { data: projects } = await response.json();

python
Python
import requests
response = requests.get(
"https://seogeo.tools/api/public/v1/projects",
headers={"Authorization": "Bearer sg_live_xxx"}
)
projects = response.json()["data"]



Get Project with Stats

bash
curl
curl -X GET "https://seogeo.tools/api/public/v1/projects/PROJECT_ID" \
-H "Authorization: Bearer sg_live_xxx"

javascript
// JavaScript
const projectId = "550e8400-e29b-41d4-a716-446655440000";
const response = await fetch(

https://seogeo.tools/api/public/v1/projects/${projectId}

,
{ headers: { "Authorization": "Bearer sg_live_xxx" } }
);
const { data: project } = await response.json();
console.log(project.stats.avgGeoScore);

python
Python
project_id = "550e8400-e29b-41d4-a716-446655440000"
response = requests.get(
f"https://seogeo.tools/api/public/v1/projects/{project_id}",
headers={"Authorization": "Bearer sg_live_xxx"}
)
project = response.json()["data"]
print(project["stats"]["avgGeoScore"])



Create a Project

bash
curl
curl -X POST "https://seogeo.tools/api/public/v1/projects" \
-H "Authorization: Bearer sg_live_xxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-key-123" \
-d '{"name": "My Website", "primaryDomain": "https://example.com"}'

javascript
// JavaScript
const response = await fetch("https://seogeo.tools/api/public/v1/projects", {
method: "POST",
headers: {
"Authorization": "Bearer sg_live_xxx",
"Content-Type": "application/json",
"Idempotency-Key": "unique-key-123"
},
body: JSON.stringify({
name: "My Website",
primaryDomain: "https://example.com"
})
});
const { data: project } = await response.json();

python
Python
response = requests.post(
"https://seogeo.tools/api/public/v1/projects",
headers={
"Authorization": "Bearer sg_live_xxx",
"Content-Type": "application/json",
"Idempotency-Key": "unique-key-123"
},
json={"name": "My Website", "primaryDomain": "https://example.com"}
)
project = response.json()["data"]



Start a Site Audit

bash
curl
curl -X POST "https://seogeo.tools/api/public/v1/projects/PROJECT_ID/audits" \
-H "Authorization: Bearer sg_live_xxx" \
-H "Content-Type: application/json" \
-d '{"seedUrl": "https://example.com", "maxPages": 25}'

javascript
// JavaScript
const projectId = "550e8400-e29b-41d4-a716-446655440000";
const response = await fetch(

https://seogeo.tools/api/public/v1/projects/${projectId}/audits

,
{
method: "POST",
headers: {
"Authorization": "Bearer sg_live_xxx",
"Content-Type": "application/json"
},
body: JSON.stringify({ seedUrl: "https://example.com", maxPages: 25 })
}
);
const { data: audit } = await response.json();
console.log("Audit ID:", audit.auditRunId);

python
Python
project_id = "550e8400-e29b-41d4-a716-446655440000"
response = requests.post(
f"https://seogeo.tools/api/public/v1/projects/{project_id}/audits",
headers={
"Authorization": "Bearer sg_live_xxx",
"Content-Type": "application/json"
},
json={"seedUrl": "https://example.com", "maxPages": 25}
)
audit = response.json()["data"]
print(f"Audit ID: {audit['auditRunId']}")



List Audit Pages with Filters

bash
curl - Filter pages with GEO score above 70
curl -X GET "https://seogeo.tools/api/public/v1/projects/PROJECT_ID/audits/AUDIT_ID/pages?minGeoScore=70" \
-H "Authorization: Bearer sg_live_xxx"

javascript
// JavaScript - Filter pages with schema.org markup
const params = new URLSearchParams({ hasSchema: "true", pageSize: "50" });
const response = await fetch(

https://seogeo.tools/api/public/v1/projects/${projectId}/audits/${auditId}/pages?${params}

,
{ headers: { "Authorization": "Bearer sg_live_xxx" } }
);
const { data: pages } = await response.json();

python
Python - Paginate through all pages
all_pages = []
page = 1
while True:
response = requests.get(
f"https://seogeo.tools/api/public/v1/projects/{project_id}/audits/{audit_id}/pages",
headers={"Authorization": "Bearer sg_live_xxx"},
params={"page": page, "pageSize": 100}
)
data = response.json()
all_pages.extend(data["data"])
if not data["meta"]["hasNextPage"]:
break
page += 1



Create Content Brief

bash
curl
curl -X POST "https://seogeo.tools/api/public/v1/projects/PROJECT_ID/content/briefs" \
-H "Authorization: Bearer sg_live_xxx" \
-H "Content-Type: application/json" \
-d '{"topic": "Best SEO practices for 2025", "audience": "marketers", "goal": "educate"}'

javascript
// JavaScript
const response = await fetch(

https://seogeo.tools/api/public/v1/projects/${projectId}/content/briefs

,
{
method: "POST",
headers: {
"Authorization": "Bearer sg_live_xxx",
"Content-Type": "application/json"
},
body: JSON.stringify({
topic: "Best SEO practices for 2025",
audience: "marketers",
goal: "educate"
})
}
);
const { data: brief } = await response.json();

python
Python
response = requests.post(
f"https://seogeo.tools/api/public/v1/projects/{project_id}/content/briefs",
headers={
"Authorization": "Bearer sg_live_xxx",
"Content-Type": "application/json"
},
json={
"topic": "Best SEO practices for 2025",
"audience": "marketers",
"goal": "educate"
}
)
brief = response.json()["data"]



Start GEO Monitor Test

bash
curl
curl -X POST "https://seogeo.tools/api/public/v1/projects/PROJECT_ID/geo-monitor/tests" \
-H "Authorization: Bearer sg_live_xxx" \
-H "Content-Type: application/json" \
-d '{"prompt": "What are the best SEO tools?", "locale": "en"}'

javascript
// JavaScript
const response = await fetch(

https://seogeo.tools/api/public/v1/projects/${projectId}/geo-monitor/tests

,
{
method: "POST",
headers: {
"Authorization": "Bearer sg_live_xxx",
"Content-Type": "application/json"
},
body: JSON.stringify({ prompt: "What are the best SEO tools?", locale: "en" })
}
);
const { data: test } = await response.json();
console.log("Test ID:", test.testId);

python
Python
response = requests.post(
f"https://seogeo.tools/api/public/v1/projects/{project_id}/geo-monitor/tests",
headers={
"Authorization": "Bearer sg_live_xxx",
"Content-Type": "application/json"
},
json={"prompt": "What are the best SEO tools?", "locale": "en"}
)
test = response.json()["data"]
print(f"Test ID: {test['testId']}")