Overview

Seonar is a technical SEO analysis API. Send a URL — get back a structured JSON audit covering up to 9 checks: robots.txt, sitemap, meta tags, canonical tags, structured data, security headers, redirect chains, hreflang, and internal links.

The API is HTTP-based, uses Bearer token authentication, and always returns the same predictable JSON shape — easy to parse in any language or pipeline.

Base URL

Authentication

All check requests require a Bearer token in the Authorization header. Obtain your token from the Dashboard after registering.

Authorization: Bearer sk_live_••••••••••••••••••••••

Creating a token

Go to the Dashboard, enter a name for the token, and click Create token. The token is shown once — copy it immediately.

You can create multiple tokens (e.g., one per project) and revoke them individually.

Quick Start

Run your first full audit in under a minute:

curl -X POST https://seonar.io/api/v1/check \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-site.com"}'

{
  "url": "https://your-site.com",
  "checked_at": "2026-02-25T10:00:00+00:00",
  "results": {
    "robots_txt":      { "status": "pass", "score": 100 },
    "sitemap":         { "status": "pass", "score": 100 },
    "meta_tags":       { "status": "warn", "score": 70  },
    "internal_links":  { "status": "fail", "score": 40  }
    // ... 5 more checks
  },
  "summary": {
    "total_checks": 9, "passed": 6, "warnings": 2,
    "failed": 1, "errors": 0, "overall_score": 82
  }
}

POST /api/v1/check

Run a technical SEO audit on a URL. Requires authentication.

Request

POST /api/v1/check
Authorization: Bearer {token}
Content-Type: application/json

{
  "url":    "https://example.com",
  "checks": ["robots_txt", "sitemap", "meta_tags"]
}

Response

Returns 200 OK with a JSON body. See Response Format for the full structure.

GET /api/v1/checks

Returns the list of all available check keys and their descriptions. No authentication required.

GET /api/v1/checks

{
  "checks": [
    { "key": "robots_txt",       "name": "robots.txt"         },
    { "key": "sitemap",           "name": "Sitemap"             },
    { "key": "meta_tags",         "name": "Meta Tags"           },
    { "key": "canonical",         "name": "Canonical"           },
    { "key": "structured_data",   "name": "Structured Data"     },
    { "key": "security_headers",  "name": "Security Headers"    },
    { "key": "redirect_chain",    "name": "Redirect Chain"      },
    { "key": "hreflang",          "name": "Hreflang"            },
    { "key": "internal_links",    "name": "Internal Links"      }
  ]
}

Response Format

Every POST /check response follows this structure:

{
  "url":        "https://example.com",        // audited URL
  "checked_at": "2026-02-25T10:00:00+00:00", // ISO 8601
  "results":    { /* keyed by check name */ },
  "summary":    { /* aggregate stats */ }
}

Check result object

Each key in results contains:

Issue object

Summary object

Rate Limits

Rate limits are enforced per API token.

When a rate limit is exceeded, the API returns 429 Too Many Requests. The response includes standard Laravel throttle headers:

X-RateLimit-Limit:     20
X-RateLimit-Remaining: 0
Retry-After:          42   # seconds until limit resets

Errors

The API uses standard HTTP status codes. Error responses always include a JSON body.

{
  "message": "The url field is required.",
  "errors": {
    "url": ["The url field is required."]
  }
}

A check-level status: "error" in a result object means that specific check could not be completed (e.g., timeout connecting to the target site). The HTTP response is still 200 OK — the error is scoped to that individual check.

robots_txt

Fetches /robots.txt from the target host and checks for correctness, crawler restrictions, and a Sitemap directive.

data fields

Scoring

• 100 File exists, no block-all, has Sitemap directive.
• 70 File exists but missing Sitemap directive.
• 10 Disallow: / found — entire site blocked.
• 0 File not found (HTTP 404).

sitemap

Discovers the sitemap URL from robots.txt or falls back to /sitemap.xml, then validates its XML structure and content.

data fields

Scoring

• 100 Sitemap found, valid XML, contains URLs.
• 60 Sitemap has more than 50,000 URLs (limit exceeded).
• 40 Sitemap contains no URLs.
• 0 Sitemap not found.

meta_tags

Fetches the page HTML and validates title length, meta description, Open Graph tags, and Twitter Card.

data fields

Scoring

• 100 All tags present and within recommended lengths.
• 70–90 Missing OG tags or title/description length outside 30–60 / 50–160 char range.
• ≤55 Missing <title> (−30) or meta description (−25).

canonical

Checks for the presence of a <link rel="canonical"> tag, verifies it is self-referencing, and detects conflicting multiple canonicals.

data fields

Scoring

• 100 Present and self-referencing.
• 70 Present but points to a different URL.
• 60 Canonical tag missing.
• 20 Multiple conflicting canonical tags.

structured_data

Finds all <script type="application/ld+json"> blocks, validates their JSON syntax, extracts schema types, and flags rich-snippet-eligible types.

data fields

Rich-eligible types

Article, BlogPosting, Product, Review, Recipe, Event, FAQPage, HowTo, Person, Organization, WebSite, BreadcrumbList, LocalBusiness, JobPosting, Course, VideoObject

security_headers

Issues a HEAD request and checks five security-related response headers, plus HTTPS enforcement. Relevant for SEO because Google gives a slight ranking signal to secure sites and headers affect trust signals.

data fields

Scoring

• 100 All headers present, HTTPS enforced.
• 80 Missing HSTS or X-Frame-Options (−10 each).
• ≤70 Site not on HTTPS (−30).

CSP, X-Content-Type-Options, and Referrer-Policy are info level — they reduce score indirectly only if combined with other issues.

redirect_chain

Follows redirects one hop at a time (max 10), recording each step. Detects loops, oversized chains, and non-HTTPS final destinations.

data fields

Scoring

• 100 No redirects, or a single clean HTTP→HTTPS redirect.
• 70 3 hops.
• 20 More than 3 hops.
• 0 Redirect loop detected.

hreflang

Detects <link rel="alternate" hreflang="…"> tags, validates language codes against BCP 47, checks for duplicates, and verifies x-default presence.

If no hreflang tags are found, the check returns pass with an informational note — single-language sites don't need hreflang.

data fields

internal_links

Parses all <a href> tags, filters to internal links (same host), deduplicates, and checks up to 20 sampled links for HTTP errors (4xx/5xx).

data fields

Scoring

• 100 All sampled links returned 2xx/3xx.
• 85–70 1–2 broken links (−15 per broken link).
• 60 No internal links found on the page at all.