API Quickstart: Your First Call in Minutes

In the dashboard: Settings → AI Agents → API Keys (admin role). Keys look like smk_live_... and are shown once at creation, so store it now. Scopes are the boundary: read:gsc and chat:ask are free; agents:act unlocks tools that stage changes.

export SEOMATIC_API_KEY=smk_live_...

curl https://app.seomatic.ai/api/v1/me \
  -H "Authorization: Bearer $SEOMATIC_API_KEY"

const res = await fetch("https://app.seomatic.ai/api/v1/me", {
  headers: { Authorization: `Bearer ${process.env.SEOMATIC_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

import os, requests

res = requests.get(
    "https://app.seomatic.ai/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['SEOMATIC_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
print(res.json())

The response returns your workspace, the key's scopes, and a capabilities block telling you which paid surfaces (REST acting, Zapier, webhooks) the plan allows, so an agent can discover entitlements without hitting a 402. The zapier flag is true on any paid plan or trial and also covers the n8n and Make integrations; actions in them follow rest_act. On the free plan, free_questions shows how many of the 5 monthly questions are left; it is null on paid plans.

{
  "workspace": {
    "id": "3f0c...",
    "name": "Acme",
    "gsc_connected": true
  },
  "crawler_ingest_url": "https://app.seomatic.ai/api/ingest/crawler/...",
  "key": {
    "environment": "live",
    "scopes": ["read:gsc", "chat:ask"]
  },
  "capabilities": {
    "rest_act": false,
    "zapier": false,
    "webhooks": false
  },
  "free_questions": {
    "monthly_limit": 5,
    "used_this_month": 1,
    "bonus_remaining": 0,
    "remaining": 4
  }
}

curl https://app.seomatic.ai/api/v1/tools \
  -H "Authorization: Bearer $SEOMATIC_API_KEY"

Returns the full scope-filtered tool roster, each with a name, description, input schema, and an acts flag. Invoke one with POST /v1/tools/{name}. See the REST API page.

Point any MCP client (Claude, Cursor) at https://app.seomatic.ai/api/mcp with the same Bearer key. See MCP server.

The same key works in no-code tools on any paid plan or trial: n8n and Make take the API key; Zapier connects with OAuth instead.

Errors come back as JSON with a human-readable error and, for most failures, a stable code to branch on:

{
  "error": "Missing or invalid API key",
  "code": "INVALID_API_KEY",
  "details": {
    "hint": "Send \"Authorization: Bearer smk_live_...\". Keys are minted in workspace settings."
  }
}

• 401: the key is missing, mistyped or revoked. Check the header is exactly Authorization: Bearer smk_live_....
• 402: the plan does not include that surface, or the free questions for the month are used up. The body carries an upgrade_url.
• 403 MISSING_SCOPE: the key lacks a scope; details.required names it.
• 429: rate limited. Wait for the seconds in the Retry-After header, then retry.

Every code is listed on the REST API page.