Developer Tools
API Reference
Full programmatic access to every feature in the platform. Build integrations, automate workflows, and extend SEO RITE.
Authentication
API requests require a Bearer token and workspace ID header. Generate API keys in Settings > API Keys.
API keys support scoped permissions: read, write, admin, and custom scopes.
Rate Limiting
Limits vary by plan. Rate limit headers are included in every response.
Exceeding the limit returns 429 status with a Retry-After header.
Base URL
All endpoints use the tRPC protocol over HTTPS. Queries use GET, mutations use POST.
All responses return JSON. Paginated endpoints include pagination metadata.
Rate Limits by Plan
| Plan | Requests / Minute | Burst Rate | Monthly Quota |
|---|---|---|---|
| Starter | 60 req/min | 10 req/sec | 50,000 |
| Growth | 200 req/min | 30 req/sec | 250,000 |
| Agency | 500 req/min | 50 req/sec | 1,000,000 |
| Enterprise | 2,000 req/min | 200 req/sec | Custom |
Endpoints
Sites
| GET | /trpc/sites.list | List all sites in workspace |
| POST | /trpc/sites.create | Add a new site |
| GET | /trpc/sites.get | Get site details with crawl summary |
| POST | /trpc/sites.update | Update site configuration |
| POST | /trpc/sites.delete | Soft-delete a site |
Audit
| GET | /trpc/audit.listFindings | List audit findings with filters |
| POST | /trpc/audit.updateFindingStatus | Update finding status |
| POST | /trpc/audit.createAction | Create AI fix action |
| POST | /trpc/audit.approveAction | Approve a pending action |
| GET | /trpc/audit.getActionHistory | Get action audit trail |
Keywords
| GET | /trpc/keywords.list | List tracked keywords |
| GET | /trpc/keywords.getRankings | Get rank observations |
| GET | /trpc/keywords.getClusters | Get keyword clusters |
| POST | /trpc/keywords.addKeywords | Add keywords to tracking |
| POST | /trpc/keywords.removeKeywords | Remove keywords from tracking |
Crawl
| POST | /trpc/crawl.createProject | Create crawl project |
| POST | /trpc/crawl.startCrawl | Start a crawl run |
| GET | /trpc/crawl.getCrawlRun | Get crawl run status |
| GET | /trpc/crawl.getPages | List crawled pages with metadata |
| POST | /trpc/crawl.cancelCrawl | Cancel a running crawl |
Content
| GET | /trpc/content.listAssets | List content assets |
| GET | /trpc/content.getScores | Get content quality scores |
| POST | /trpc/content.createBrief | Generate a content brief |
| POST | /trpc/content.refreshAnalysis | Refresh content scoring |
Reports & Automations
| GET | /trpc/competitors.list | List tracked competitors |
| GET | /trpc/geo.getObservations | Get GEO visibility data |
| POST | /trpc/reports.generateReport | Generate a report |
| GET | /trpc/automations.listRules | List automation rules |
| GET | /trpc/activity.getLog | Get activity audit log |
Code Examples
# List sites in your workspace
curl -X GET "https://api.seo-rite.com/trpc/sites.list?input={}" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json"
# Create a new site
curl -X POST "https://api.seo-rite.com/trpc/sites.create" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{"name":"My Site","domain":"example.com","primaryUrl":"https://example.com"}'
# Get audit findings (critical and high severity)
curl -X GET "https://api.seo-rite.com/trpc/audit.listFindings" \
-G --data-urlencode 'input={"siteId":"SITE_ID","severity":["CRITICAL","HIGH"],"status":"OPEN"}' \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID"import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from '@seo-rite/api';
const client = createTRPCProxyClient<AppRouter>({
links: [
httpBatchLink({
url: 'https://api.seo-rite.com/trpc',
headers: {
Authorization: `Bearer ${token}`,
'X-Workspace-Id': workspaceId,
},
}),
],
});
// List sites
const sites = await client.sites.list.query({
limit: 25,
sortBy: 'createdAt',
sortOrder: 'desc',
});
// Create a site
const newSite = await client.sites.create.mutate({
name: 'My Site',
domain: 'example.com',
primaryUrl: 'https://example.com',
platformType: 'wordpress',
});
// Approve an AI fix action
const approved = await client.audit.approveAction.mutate({
actionId: 'action-id',
notes: 'Looks good, approved for publishing.',
});import requests
import json
BASE_URL = "https://api.seo-rite.com/trpc"
HEADERS = {
"Authorization": f"Bearer {token}",
"X-Workspace-Id": workspace_id,
"Content-Type": "application/json",
}
# List sites
response = requests.get(
f"{BASE_URL}/sites.list",
params={"input": "{}"},
headers=HEADERS,
)
sites = response.json()["result"]["data"]
# Create a site
response = requests.post(
f"{BASE_URL}/sites.create",
json={
"name": "My Site",
"domain": "example.com",
"primaryUrl": "https://example.com",
"platformType": "wordpress",
},
headers=HEADERS,
)
new_site = response.json()["result"]["data"]
# Get audit findings
response = requests.get(
f"{BASE_URL}/audit.listFindings",
params={"input": json.dumps({
"siteId": new_site["id"],
"severity": ["CRITICAL", "HIGH"],
"status": "OPEN",
})},
headers=HEADERS,
)
findings = response.json()["result"]["data"]Webhook Events
Subscribe to events via the Integrations settings or the webhooks API. All payloads include a signature header for verification.
| Event | Description |
|---|---|
| crawl.completed | Fired when a crawl run finishes |
| crawl.failed | Fired when a crawl run fails |
| finding.created | New audit finding detected |
| action.approved | AI fix action approved |
| action.published | Fix published to CMS |
| action.failed | Publish action failed |
| rank.anomaly | Significant rank change detected |
| content.decay | Content decay threshold reached |
| integration.disconnected | Integration auth expired |
OpenAPI Specification
Download the full OpenAPI 3.1 spec for code generation, testing, and documentation tooling.
Official SDKs
Use our official client libraries for type-safe API access in your language of choice.
npm install @seo-rite/sdkstablepip install seo-ritestablegem install seo_ritebetaNeed help with the API?
Check the full documentation or reach out to our developer support team.