API Quick Start

Get started with the SEOGEO Tools API in 5 minutes. This guide walks you through creating an API key and making your first API call.

Prerequisites

A SEOGEO Tools account (any plan)
At least one project created

Step 1: Create an API Key

Go to Settings > API Keys
Click Create API Key
Enter a name (e.g., "My Integration")
Select scopes (or leave all enabled)
Click Create
Copy the key immediately - it won't be shown again

Step 2: Make Your First Request

Test your key by fetching your user info:

``bash


Replace sg_live_xxx with your actual API key
curl -X GET "https://seogeo.tools/api/public/v1/me" \
-H "Authorization: Bearer sg_live_xxx"



Expected response:

json
{
"data": {
"userId": "550e8400-e29b-41d4-a716-446655440000",
"email": "you@example.com",
"plan": "pro",
"apiKeyPrefix": "sg_live_"
},
"meta": {
"requestId": "req_abc123"
}
}



Step 3: List Your Projects

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

json
{
"data": [
{
"id": "project-uuid-1",
"name": "My Website",
"primaryDomain": "https://example.com",
"createdAt": "2025-01-15T10:00:00Z"
}
],
"meta": {
"page": 1,
"pageSize": 20,
"total": 1,
"totalPages": 1,
"hasNextPage": false,
"requestId": "req_def456"
}
}



Step 4: Start an Audit

bash
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}'

json
{
"data": {
"auditRunId": "audit-uuid-1",
"status": "pending",
"jobId": "job-uuid-1"
},
"meta": {
"requestId": "req_ghi789"
}
}



JavaScript SDK Example

javascript
const API_KEY = "sg_live_xxx";
const BASE_URL = "https://seogeo.tools/api/public/v1";

async function listProjects() {

const response = await fetch(${BASE_URL}/projects, {

headers: { "Authorization": Bearer ${API_KEY} }


});
return response.json();
}

async function startAudit(projectId, seedUrl) {

const response = await fetch(${BASE_URL}/projects/${projectId}/audits, {


method: "POST",
headers: {

"Authorization": Bearer ${API_KEY},


"Content-Type": "application/json"
},
body: JSON.stringify({ seedUrl, maxPages: 25 })
});
return response.json();
}

// Usage
const { data: projects } = await listProjects();
const { data: audit } = await startAudit(projects[0].id, "https://example.com");
console.log("Audit started:", audit.auditRunId);



Python SDK Example

python
import requests

API_KEY = "sg_live_xxx"
BASE_URL = "https://seogeo.tools/api/public/v1"

def list_projects():
response = requests.get(
f"{BASE_URL}/projects",
headers={"Authorization": f"Bearer {API_KEY}"}
)
return response.json()

def start_audit(project_id, seed_url):
response = requests.post(
f"{BASE_URL}/projects/{project_id}/audits",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json={"seedUrl": seed_url, "maxPages": 25}
)
return response.json()

Usage
projects = list_projects()["data"]
audit = start_audit(projects[0]["id"], "https://example.com")["data"]
print(f"Audit started: {audit['auditRunId']}")

Next Steps

Authentication - Learn about scopes and key management
Rate Limits - Understand rate limiting
API Reference - Complete endpoint documentation
Examples - More code examples