Authentication

Every request to the SnowSEO API must be authenticated with an API key. There’s no OAuth flow for the REST API - just include your key and you’re good to go. Send it as Authorization: Bearer <key> or in an x-api-key header.

Quick Start

If you already have an API key, here’s the fastest way to make a request:

curl -N https://api.snowseo.com/v3/seo-audit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "example.com"}'

Replace YOUR_API_KEY with your actual key (a brand key starts with sk_team_, an organization key with sk_org_; older brand keys start with plain sk_ and keep working). Add Content-Type: application/json whenever you send a body. A single-page audit streams newline-delimited JSON (status lines, then the result on the last line), so -N shows progress as it arrives.

Creating an API Key

Go to the API settings page

In the SnowSEO dashboard, navigate to Settings → Integrations → API. Only organization admins and owners can create or delete keys, and the organization needs the Scale plan.

Create a new key

Under Brand API keys (one brand) or Organization API keys (every brand), click Create new key. Give it a descriptive name so you remember what it’s for - e.g., Production Server, CI/CD Pipeline, or Analytics Dashboard. See Key Scopes to choose between them.

Copy and store the key immediately

The full key is shown only once after creation. Copy it right away and store it in a secure location.

If you lose the key, there’s no way to retrieve it. Delete it and create a new one.

Making Your First Request

Here’s a complete example showing how to call the API from different environments:

Node.js
Python
Next.js API Route

// Using the built-in fetch (Node 18+)
const response = await fetch('https://api.snowseo.com/v3/seo-audit', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SNOWSEO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'example.com' }),
});

if (!response.ok) {
  const error = await response.json();
  console.error('API Error:', error);
  throw new Error(`HTTP ${response.status}: ${error.message}`);
}

// The audit streams NDJSON: status lines, then the result on the last line
const lines = (await response.text()).split('\n').filter((l) => l.trim());
const data = JSON.parse(lines.at(-1));
if (data.error) throw new Error(data.error); // in-band errors arrive with HTTP 200
console.log('SEO Score:', data.seoAudit?.overallScore);

Always check response.ok or response.status before trying to parse the body. For streamed endpoints, also check the last line for an error field.

import httpx
import os
import json

client = httpx.Client(
    base_url="https://api.snowseo.com",
    headers={"Authorization": f"Bearer {os.environ['SNOWSEO_API_KEY']}"},
    timeout=30.0,
)

try:
    response = client.post("/v3/seo-audit", json={"url": "example.com"})
    response.raise_for_status()  # Raises for 4xx/5xx errors
    # The audit streams NDJSON: status lines, then the result on the last line
    lines = [line for line in response.text.splitlines() if line.strip()]
    data = json.loads(lines[-1])
    if "error" in data:  # in-band errors arrive with HTTP 200
        raise RuntimeError(data["error"])
    print(f"SEO Score: {data['seoAudit']['overallScore']}")
except httpx.HTTPStatusError as e:
    print(f"API Error: {e.response.json()}")
except httpx.TimeoutException:
    print("Request timed out")

Set a timeout on your HTTP client. The SnowSEO API can take several seconds for heavy operations like multi-page site audits.

// pages/api/seo-check.ts or app/api/seo-check/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const url = searchParams.get('url');

  if (!url) {
    return NextResponse.json(
      { error: 'URL parameter is required' },
      { status: 400 }
    );
  }

  const apiKey = process.env.SNOWSEO_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: 'API key not configured' },
      { status: 500 }
    );
  }

  const response = await fetch('https://api.snowseo.com/v3/seo-audit', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url }),
  });

  // Pass the body through untouched: a single-page audit streams NDJSON
  return new Response(response.body, {
    status: response.status,
    headers: {
      'Content-Type':
        response.headers.get('content-type') ?? 'application/json',
    },
  });
}

Key Scopes & Permissions

There are two kinds of key. Pick a brand key when an integration only needs one brand, and an organization key when one integration works across all of them.

	Brand key	Organization key
Prefix	`sk_team_` (older keys: `sk_`)	`sk_org_`
Reaches	One brand	Every brand in the organization
Brand per request	Carried by the key; no `teamId` needed	Pass the brand’s `teamId` on every team-scoped request
Organization endpoints	Not available	Brands Overview and listing brands (`GET /v3/mcp/teams`)
Keys allowed	Several per brand	Several per organization

Brand keys. The key carries your organization and brand, so you don’t pass teamId. If you do pass a teamId (or teamIds), it must be the key’s own brand; any other brand returns 403 with code API_KEY_TEAM_MISMATCH. Organization-level endpoints return 403 with code API_KEY_ROUTE_NOT_ALLOWED. Organization keys. Name the brand on each request with teamId (query string for reads, body for writes). Call GET /v3/mcp/teams first to list the brands and their IDs. A team-scoped request without teamId returns 400, and a brand from another organization returns 403 with code API_KEY_TEAM_MISMATCH.

An organization key can read and change every brand in the organization. Prefer brand keys where one brand is enough, and keep organization keys to trusted servers.

Endpoints tied to a person rather than a brand, such as Ask Snowy chats, can’t be called with either kind of key and return 403 with code API_KEY_ROUTE_NOT_ALLOWED.

Common Integration Patterns

Serverless Functions (Vercel, Netlify, etc.)

// Never call the SnowSEO API directly from the browser.
// Always proxy through your serverless function.
export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  const { url } = req.body;

  const response = await fetch('https://api.snowseo.com/v3/seo-audit', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SNOWSEO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url }),
  });

  // Single-page audits stream NDJSON, so forward the raw text and content type
  res.setHeader('Content-Type', response.headers.get('content-type') ?? 'application/json');
  return res.status(response.status).send(await response.text());
}

Webhook Handler (Receiving Data)

If you’re building an integration that receives webhooks from SnowSEO (e.g., article published events), validate the Authorization header:

export default function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).send('Method Not Allowed');
  }

  const authHeader = req.headers.authorization;
  const token = authHeader?.replace('Bearer ', '');

  // Validate against your stored secret
  if (token !== process.env.MY_WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const { event, article } = req.body;

  if (event === 'article.published') {
    console.log(`Article published: ${article.title}`);
    console.log(`URL: ${article.slug}`);
  }

  res.status(200).json({ received: true });
}

Automated Reporting Script

// Run this on a schedule (e.g., cron job)
import cron from 'node-cron';

async function fetchKeywordReport() {
  const response = await fetch('https://api.snowseo.com/v3/rank-tracking/keywords', {
    headers: { 'Authorization': `Bearer ${process.env.SNOWSEO_API_KEY}` },
  });

  if (!response.ok) {
    throw new Error(`Failed to fetch keywords: ${response.status}`);
  }

  const { items } = await response.json();
  return items.filter(k => k.position <= 10);
}

// Schedule daily at 9 AM
cron.schedule('0 9 * * *', async () => {
  console.log('Running daily keyword report...');
  const topKeywords = await fetchKeywordReport();
  console.log(`Found ${topKeywords.length} keywords in top 10`);
});

Error Handling

The API returns structured error responses. Here’s how to handle them properly:

async function safeApiCall(endpoint, options = {}) {
  const url = endpoint.startsWith('http')
    ? endpoint
    : `https://api.snowseo.com${endpoint}`;

  const response = await fetch(url, {
    ...options,
    headers: {
      'Authorization': `Bearer ${process.env.SNOWSEO_API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  // Parse the last non-empty line: streamed endpoints send NDJSON, others a single JSON body
  const text = await response.text();
  const lastLine = text.split('\n').filter((l) => l.trim()).at(-1);
  let data = {};
  try { data = lastLine ? JSON.parse(lastLine) : {}; } catch {}

  if (response.ok && data.error) {
    // Streamed endpoints report failures in-band with HTTP 200
    throw new Error(`API Error: ${data.error}`);
  }

  if (!response.ok) {
    // Handle specific error codes
    switch (response.status) {
      case 401:
        throw new Error('Invalid or expired API key. Check SNOWSEO_API_KEY.');
      case 402:
        throw new Error('Not enough credits or balance for this operation.');
      case 403:
        throw new Error(`Access denied: ${data.error || data.message || 'Forbidden'}`);
      case 429:
        const retryAfter = data.retryAfterSeconds || 60;
        throw new Error(`Rate limited. Retry after ${retryAfter} seconds.`);
      case 500:
        throw new Error('SnowSEO API error. Try again later.');
      default:
        throw new Error(`API Error: ${data.message || response.statusText}`);
    }
  }

  return data;
}

// Usage
try {
  const audit = await safeApiCall('/v3/seo-audit', {
    method: 'POST',
    body: JSON.stringify({ url: 'example.com' }),
  });
  console.log(`Score: ${audit.seoAudit.overallScore}`);
} catch (error) {
  console.error(error.message);
  // Decide: retry, alert, or graceful degradation
}

Error Reference

The error field holds a human-readable message (e.g. "teamId is required", "Team not found", "Rate limit exceeded."). Some errors also include a machine-readable code, such as UNAUTHORIZED, FST_ERR_VALIDATION, MCP_TOOL_DISABLED, or SCALE_PLAN_REQUIRED; IndexNow endpoints return message only. Branch on the HTTP status code (and code when present), and surface error / message to the user.

HTTP Status	Cause	Resolution
`400`	Bad request - required field missing or malformed	Check the `error` message for which field
`401`	Missing or invalid API key	Verify your API key is correct
`402`	Not enough credits or balance for the operation	Top up or wait for your balance to renew
`403`	Valid key but no access, or a plan/usage limit was hit	`API_KEY_TEAM_MISMATCH`: use the key’s own brand, or for an organization key a brand in its organization. `API_KEY_ROUTE_NOT_ALLOWED`: the endpoint isn’t available to API keys. Otherwise you’ve exceeded your plan limit
`404`	Resource doesn’t exist	Check the ID is correct
`409`	Conflict, such as an audit already running	Wait for the running job to finish
`429`	Too many requests	Wait and retry (see `retryAfterSeconds`)
`500`	Server-side error	Retry with exponential backoff
`503`	Temporary outage	Retry after a delay

Security Best Practices

Never expose your API key in frontend code, public repositories, or logs. Anyone with your key can access your SnowSEO data.

Use environment variables

Always store your key in an environment variable, never hardcoded:

# .env (add this to .gitignore)
SNOWSEO_API_KEY=sk_team_xxxxxxxxxxxxxxxxxxxx

// Good
const apiKey = process.env.SNOWSEO_API_KEY;

// Bad - key visible in code
const apiKey = 'sk_team_abc123...';

Never commit secrets to version control

Add your .env file to .gitignore:

# Environment variables
.env
.env.local
.env.production

For GitHub, use Secrets (Settings → Secrets and variables → Actions) to store API keys for CI/CD pipelines.

Use separate keys per environment

Create different API keys for development, staging, and production:

MyApp-Dev
MyApp-Staging
MyApp-Production

This way you can revoke a compromised key without affecting other environments.

Rotate keys periodically

Rotate your API keys every 90 days or immediately if you suspect compromise:

Create a new key in the dashboard
Update your environment variable
Deploy and verify it works
Delete the old key

This gives you zero downtime while staying secure.

Validate incoming webhooks

If you’re receiving webhooks from SnowSEO, always validate the Authorization header against your stored secret:

function validateWebhook(req, secret) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  return token === secret;
}

Rate Limits & Retries

Each API key is capped at 120 requests per 60 seconds. Routes also have their own limits (for example 100 per minute for /v3/seo-audit and 150 for rank tracking), and there is a global cap of 240 requests per minute for the organization. If you exceed any of these, you’ll get a 429 response with a retryAfterSeconds hint (the key-level limit also sends a Retry-After header and code RATE_LIMITED):

{
  "success": false,
  "statusCode": 429,
  "code": "TOO_MANY_REQUESTS",
  "error": "Rate limit exceeded.",
  "message": "Rate limit exceeded.",
  "retryAfterSeconds": 60
}

Implementing Retry Logic

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = parseInt(
          response.headers.get('retry-after') || '5',
          10
        );
        const backoff = retryAfter * 1000 * Math.pow(2, attempt);

        console.log(`Rate limited. Waiting ${backoff}ms before retry...`);
        await new Promise(resolve => setTimeout(resolve, backoff));
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await new Promise(resolve =>
        setTimeout(resolve, 1000 * Math.pow(2, attempt))
      );
    }
  }
  throw new Error('Max retries exceeded');
}

// Usage
const response = await fetchWithRetry(
  'https://api.snowseo.com/v3/seo-audit',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SNOWSEO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url: 'example.com' }),
  }
);

Quick Test

Verify your key works with a simple request:

curl https://api.snowseo.com/v3/rank-tracking/keywords \
  -H "Authorization: Bearer YOUR_API_KEY"

Expected response (200 OK):

{
  "items": [],
  "page": 1,
  "pageSize": 50,
  "total": 0,
  "totalPages": 0
}

If you get 401 Unauthorized, double-check:

The key is correctly set in your environment variable
You’re using Bearer (with the space) before the key
The key hasn’t been deleted from the dashboard

Overview

Website Analysis

PageSpeed

Pages & Folders

Keywords & Research

Topic Clusters

Traffic & Analytics

AI Visibility

Rank Tracking

Article Generation

Content

Content Utilities

Backlink Outreach

Exports

Reports

Dashboard

Ask Snowy

Settings

Quick Start

Creating an API Key

Making Your First Request

Key Scopes & Permissions

Common Integration Patterns

Serverless Functions (Vercel, Netlify, etc.)

Webhook Handler (Receiving Data)

Automated Reporting Script

Error Handling

Error Reference

Security Best Practices

Rate Limits & Retries

Implementing Retry Logic

Quick Test

​Quick Start

​Creating an API Key

​Making Your First Request

​Key Scopes & Permissions

​Common Integration Patterns

​Serverless Functions (Vercel, Netlify, etc.)

​Webhook Handler (Receiving Data)

​Automated Reporting Script

​Error Handling

​Error Reference

​Security Best Practices

​Rate Limits & Retries

​Implementing Retry Logic

​Quick Test

Quick Start

Creating an API Key

Making Your First Request

Key Scopes & Permissions

Common Integration Patterns

Serverless Functions (Vercel, Netlify, etc.)

Webhook Handler (Receiving Data)

Automated Reporting Script

Error Handling

Error Reference

Security Best Practices

Rate Limits & Retries

Implementing Retry Logic

Quick Test