Skip to content
SerpTorch

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

API tokens

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).

Something unclear or missing? Tell us and we will add it.