The SEO Agent API.

Every request carries an API key as a bearer token. Keys look like sk_live_... and are minted in the app under Settings, API keys (org admins only; the full key is shown once at creation). Keys are scoped to your organization and carry all scopes by default.

curl https://www.theseoagent.ai/api/v1/projects \
  -H "Authorization: Bearer sk_live_..."

A missing or invalid key returns 401 unauthorized. A valid key on an organization without an active subscription returns 402 subscription_required. API access is included in the $99/mo plan, no separate API pricing. Pricing.

Every response is JSON with the same envelope. Success wraps the payload in data; errors carry a stable machine-readable code. Both include a request_id you can quote in support requests.

// Success
{ "data": { ... }, "request_id": "3f6c..." }

// Error
{ "error": { "code": "not_found", "message": "Project not found in this organization." },
  "request_id": "3f6c..." }

Error codes you can hit on any endpoint:

Per key: 60 requests per minute and 1,000 per day. The endpoints that spend real data budget carry their own daily caps, applied per key and per organization:

• POST /agents/keyword-research: 10 runs per day.
• POST /agents/audit: 5 runs per day.
• POST /agents/generate: 1 article per project per day (the same cap as the in-app Generate button). Returns 429 daily_limit_reached when spent.

Every 429 includes retry_after_seconds in the body and a standard Retry-After header. Back off and retry after that window.

Send an Idempotency-Key header on any POST to make retries safe. The first call reserves the key and stores its response; a retry with the same key and the same body replays the stored response instead of running the operation twice.

curl -X POST https://www.theseoagent.ai/api/v1/agents/generate \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 9f2b7c1e-article-monday" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "...", "keyword": "ai seo agent"}'

Reusing a key with a different body returns 409 idempotency_key_reused. Retrying while the first request is still running returns 409 request_in_progress.

The three agent endpoints that do real work (generate, keyword-research, audit) respond 202 with a job_id and a poll_url, then run in the background. Poll GET /jobs/:id every few seconds until the status is terminal:

• succeeded: done. Generation jobs set article_id; audit jobs set report_url.
• failed: the error field carries a stable code or message.
• canceled: the job was canceled in the app.

Non-terminal statuses are pending and running. Keyword research typically lands in 2 to 6 minutes; audits in 1 to 5 minutes; generation in a few minutes depending on article length. If you would rather not poll, subscribe to webhooks below.

Subscribe at Settings, Webhooks. Two events fire today: article.published (an article was published to your CMS) and audit.completed (an audit finished, successfully or not). Two more are reserved and subscribable now so existing subscriptions keep working when they ship: article.failed and keywords.ready.

Every delivery is a POST with the envelope { event_type, event_id, version: "1", timestamp, data }. Dedupe on event_id. Failed deliveries are retried with exponential backoff for over 24 hours.

// article.published
{ "event_type": "article.published", "event_id": "...", "version": "1",
  "timestamp": "2026-06-10T01:23:45.000Z",
  "data": { "articles": [ {
      "id": "...", "title": "...", "slug": "...",
      "content_markdown": "...", "content_html": "...",
      "meta_description": "...", "image_url": "...", "tags": [],
      "excerpt": "...", "read_time_minutes": 7, "faqs": [],
      "created_at": "...", "published_url": "https://acme.com/blog/..." } ] } }

// audit.completed
{ "event_type": "audit.completed", "event_id": "...", "version": "1",
  "timestamp": "2026-06-10T01:23:45.000Z",
  "data": { "domain": "example.com",
    "report_url": "https://www.theseoagent.ai/seo-audit/example.com",
    "status": "completed" } }

audit.completed fires on failures too, with status: "failed" and report_url: null.

Verifying signatures

Every delivery is signed with your webhook's secret (shown once at creation). The x-seobot-signature header is t=<unix seconds>,v1=<hex> where v1 is the HMAC-SHA256 of `${t}.${rawBody}` keyed with the secret. Verify the HMAC over the raw request body (before any JSON parsing) and reject timestamps older than 5 minutes to block replays:

const { createHmac, timingSafeEqual } = require("node:crypto");

function verify(secret, rawBody, header, toleranceSec = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=", 2))
  );
  const t = Number.parseInt(parts.t, 10);
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;

  const expected = createHmac("sha256", secret)
    .update(t + "." + rawBody)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 ?? "", "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

// Express example: capture the RAW body, not the parsed one.
app.post("/hooks/seoagent", express.raw({ type: "*/*" }), (req, res) => {
  const ok = verify(process.env.WEBHOOK_SECRET, req.body.toString("utf8"),
    req.header("x-seobot-signature") ?? "");
  if (!ok) return res.status(401).end();
  const event = JSON.parse(req.body.toString("utf8"));
  // handle event.event_type
  res.status(200).end();
});

The Send test button on Settings, Webhooks fires a signed sample delivery so you can verify your receiver end to end before anything real happens.

Sign up free, mint a key under Settings, API keys, and start the $1 trial to activate it. API access is part of the single $99/mo plan. Simple pricing. Real cancellation. No tricks.