REST API and webhooks
Authentication
Workspace owners create tokens in Settings → API tokens. Send the token as a Bearer header:
curl -H "Authorization: Bearer lf_xxxxxxxx" -H "Accept: application/json" https://serptorch.com/api/v1/me

A token acts as the user who created it, in that workspace. Owner and manager tokens can write; writer tokens can also generate content; client tokens are read-only. Limit: 120 requests per minute.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/me |
Workspace, credits, plan, your role |
| GET | /api/v1/projects |
List sites (called projects in the API) |
| POST | /api/v1/projects |
Add a site: name, url, optional brand_name, keywords{primary[],partial[],branded[],lsi[]}, target_urls[], language |
| GET | /api/v1/playbooks |
List playbook keys |
| GET | /api/v1/campaigns?status=running |
List campaigns |
| GET | /api/v1/campaigns/{id} |
Campaign with progress |
| POST | /api/v1/campaigns |
Create from a playbook: project_id, name, playbook, optional drip_days, start (true to start now) |
| POST | /api/v1/campaigns/{id}/start |
Start (or resume) |
| POST | /api/v1/campaigns/{id}/pause |
Pause |
| GET | /api/v1/links?project_id=&campaign_id=&status=&per_page= |
Links |
| POST | /api/v1/content/generate |
type, topic, optional quantity (1-5), project_id, words, provider |
| GET | /api/v1/grid/{id}/heatmaps |
Heatmaps for a Local Grid business |
| POST | /api/v1/grid/{id}/heatmaps |
Run: keywords[], optional grid_size |
| GET | /api/v1/ranks?project_id= |
Tracked keywords |
| GET | /api/v1/audits |
Site audits (score, status, summary) |
| GET | /api/v1/audits/{id} |
One audit with every issue (code, severity, title, URL, message, fix status) |
| POST | /api/v1/audits |
Start an audit: project_id, optional max_pages, start_url, with_pagespeed. Returns 202 |
| GET | /api/v1/research/{type}?domain=&country=&provider=&limit= |
SEO data. type is overview, backlinks, refdomains, keywords, competitors or keyword_research (pass keywords= instead of domain=). Owners and managers fetch when not cached (costs credits); other roles read the cache only |
The API and webhooks are part of the Agency tool (the Agency plan, or Agency added to any plan for $59 a month). Each call also needs the tool it belongs to: for example /api/v1/grid needs Local.
Errors return JSON {"message": "..."} with status 401 (bad token), 402 (not enough credits or allowance left), 403 (role, or a tool your plan does not include; the response names the tool), 404, 422 (validation).
Example: create and start a campaign
curl -X POST https://serptorch.com/api/v1/campaigns \
-H "Authorization: Bearer lf_xxxxxxxx" -H "Content-Type: application/json" \
-d '{"project_id": 1, "name": "Q1 authority", "playbook": "authority_stack", "start": true}'
Outgoing webhooks
Set a URL in Settings → Webhooks. SerpTorch POSTs JSON:
{ "event": "link.published", "data": { "link_id": 42, "source_url": "…", "target_url": "…", "anchor": "…", "tier": 1 }, "sent_at": "2026-01-01T10:00:00+00:00" }
Events: link.published, link.lost, campaign.completed, heatmap.completed, order.delivered, payment.paid (and ping for tests).
Verify the X-SerpTorch-Signature header, which is HMAC-SHA256(raw body, your signing secret):
$valid = hash_equals(hash_hmac('sha256', file_get_contents('php://input'), $secret), $_SERVER['HTTP_X_SERPTORCH_SIGNATURE'] ?? '');
Failed deliveries are retried twice (after 1 and 5 minutes).