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
- Authentication - Learn about scopes and key management
- Rate Limits - Understand rate limiting
- API Reference - Complete endpoint documentation
- Examples - More code examples
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']}")
``