Documentation

Quickstart

AgentSEO is a token-optimized SEO intelligence API for builders. The fastest path is simple: create a key, send one async request, poll the job, then plug the same workflow into Node, Python, or MCP.

Treat queued jobs as the normal production path. Use ?sync=true only for short inline waits, demos, and fast checks.

Create API KeyOpen Playground
Auth

REST uses x-api-key. Hosted MCP accepts Bearer auth.

Default model

POST a workflow, store the returned jobId, then poll or subscribe to events.

Best inputs

Send location_code when you know it, and set project/workflow attribution early.

1. Make one successful request with cURL

Start with a single queued request. This is the clearest way to learn the API shape before you adopt an SDK or agent runtime.

Submit a search job

curl -X POST https://www.agentseo.dev/api/v1/search \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "x-project-id: demo-app" \
  -H "x-workflow-id: first-request" \
  -d '{
    "query": "family dentist austin texas",
    "location": "Austin, TX",
    "location_code": 1026201,
    "limit": 5
  }'

Typical queued response

{
  "jobId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "queued",
  "poll_url": "/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000",
  "events_url": "/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000/events",
  "retry_after_seconds": 2
}

Poll the job

curl https://www.agentseo.dev/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: sk_live_your_key_here"

Keep polling until the job returns status: "completed" or status: "failed". The completed job envelope includes the final result under result.

2. Then move to your runtime

Once you understand the queued job shape, pick the integration that matches how you build: app backend, Python workflow, or MCP-based agent tooling.

Node.js

Best default for SaaS backends, Next.js apps, workers, and programmatic SEO pipelines.

npm i @agentseo/sdk
import { AgentSEO } from "@agentseo/sdk";

const client = new AgentSEO({
  apiKey: process.env.AGENTSEO_API_KEY!,
  projectId: "client-alpha",
  workflowId: "nightly-refresh",
});

const queued = await client.contentGap(
  {
    url: "https://coolcreekfamilydental.com",
    keyword: "family dentist austin texas",
    location: "Austin, TX",
    location_code: 1026201,
    language: "en",
  },
  { idempotencyKey: "content-gap-austin-001" }
);

const status = await client.waitForJob(queued.jobId, {
  timeoutMs: 90_000,
});

if (status.status === "failed") {
  throw new Error(status.error?.message || "Job failed");
}

console.log(status.result);

Python

Good for scripts, notebooks, cron jobs, and internal analysis tooling.

pip install agentseo-sdk
from agentseo_sdk import AgentSEOClient

client = AgentSEOClient(
    api_key="sk_live_...",
    project_id="client-alpha",
    workflow_id="nightly-refresh",
)

queued = client.analyze_serp(
    keyword="family dentist austin texas",
    location="Austin, TX",
    location_code=1026201,
    language="en",
)

status = client.wait_for_job(
    queued["jobId"],
    timeout_seconds=90,
)

if status["status"] == "failed":
    raise RuntimeError(status["error"]["message"])

print(status["result"])

Hosted MCP

Best when you want AgentSEO tools inside Claude Code, Cursor, or another MCP-capable client without building the wrapper yourself.

claude mcp add --transport http agentseo https://www.agentseo.dev/mcp \
  --header "Authorization: Bearer sk_live_..." \
  --header "x-project-id: client-alpha" \
  --header "x-workflow-id: nightly-refresh"

Hosted MCP requires a server-side key with no allowed domains. If your key is restricted to browser origins, use a backend or local MCP process instead.

Need a runtime-specific guide?

Quickstart teaches the common request pattern first. For packaging and setup by tool, use the integration guides for n8n, Make, Claude Code or Claude Desktop for MCP-based use, and OpenClaw.

3. Production defaults that save time later

Request handling

  • Use queued jobs by default. Long-running SEO workflows should not assume a single synchronous response.
  • Send an idempotency-key on retried POST requests.
  • Respect rate-limit headers and retry only transient 429/5xx cases.

Input quality

  • Prefer location_code over freeform location text when you already know the target geography.
  • Set x-project-id and x-workflow-id so usage and jobs are traceable across tenants and agents.
  • Start with one workflow that proves value, then add others once you trust the job model.

Next Steps

After the first successful request, wire up auth, error handling, and the endpoint reference you actually need.

Authentication Errors & Limits API Reference