REST API Reference
Complete reference for the SEO Sniper REST API. Fetch your articles programmatically for any platform or integration.
Authentication
All API requests require a Bearer token in the Authorization header. Generate tokens in Settings → Integrations.
Authorization: Bearer sst_your_token_hereSecurity Note
Keep your API tokens secret. Never expose them in client-side code. Use environment variables for server-side requests.
Base URL
All API requests use the same base URL — your site token (generated in Settings → Integrations → API Tokens) determines which site's articles you receive.
https://api.seosniper.ioStore this as SEOSNIPER_API_URL in your environment variables.
Endpoints
/api/v1/articles
List all published articles for your site with pagination.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 10 | Number of articles (max 50) |
offset | number | 0 | Number of articles to skip |
curl -X GET "https://api.seosniper.io/api/v1/articles?limit=10&offset=0" \
-H "Authorization: Bearer sst_your_token_here"/api/v1/articles/:slug
Get a single article by its slug. Returns JSON with all article fields.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
slug | string | The article's URL slug |
curl -X GET "https://api.seosniper.io/api/v1/articles/best-coffee-shops-austin" \
-H "Authorization: Bearer sst_your_token_here"/api/v1/articles/:slug/html
Get a complete, standalone HTML document for the article. Perfect for static site generation - save directly as an HTML file.
Returns text/html instead of JSON. Includes full DOCTYPE, meta tags, Open Graph, and embedded styles.
curl -X GET "https://api.seosniper.io/api/v1/articles/best-coffee-shops-austin/html" \
-H "Authorization: Bearer sst_your_token_here" \
-o article.html/api/v1/sitemap
Get sitemap data for all published articles. Use this to generate your sitemap.xml file.
curl -X GET "https://api.seosniper.io/api/v1/sitemap" \
-H "Authorization: Bearer sst_your_token_here"Error Responses
All errors return JSON with an error field.
| Status | Error | Description |
|---|---|---|
401 | Missing or invalid Authorization header | No Bearer token provided |
401 | Invalid or revoked token | Token does not exist or was revoked |
403 | Token does not have read permission | Token lacks the "read" permission |
404 | Article not found | No published article with that slug |
{
"error": "Article not found"
}Article Object
Complete reference for the article object returned by the API.
| Field | Type | Description |
|---|---|---|
id | string | Unique article identifier |
slug | string | URL-safe slug for the article |
title | string | Article title |
metaTitle | string | SEO title for <title> tag |
metaDescription | string | SEO meta description |
contentHtml | string | Raw HTML content (no styles) |
styledContentHtml | string | HTML with applied styles (use this for rendering) |
contentMarkdown | string | Original markdown content |
headings | object | Extracted headings (h1, h2, h3 arrays) |
keywordsUsed | string[] | Keywords targeted in the article |
publishedAt | string | null | ISO 8601 publish date |
wordCount | number | Article word count |
tone | string | Article tone (professional, casual, etc.) |
featuredImageUrl | string | null | Featured image URL |
featuredImageAlt | string | null | Featured image alt text |
blogStyle | object | null | Style settings (template, customCss, stylingMethod) |
Rate Limits
API requests are rate-limited to protect the service. Current limits:
- 60 requests per minute per token
- Responses are cached for 60 seconds (Cache-Control header)
If you need higher limits for your use case, please contact support.
Frequently Asked Questions
How do I authenticate API requests?
Send your site token in the Authorization header as a Bearer token — it starts with sst_. Generate and revoke tokens anytime under Settings → Integrations → API Tokens.
Should I call the API from the browser?
No. Keep your token server-side — in an API route, build step, or backend service. Exposing it in client-side JavaScript would let anyone read it, so treat your token like a password.
How do I keep my site's content fresh?
Rather than polling the API on every request, fetch at build time or cache the response (the API already sets a 60-second Cache-Control header), then use a webhook (Settings → Webhooks) to rebuild or revalidate whenever an article is published or updated.
What does the article payload include?
Each article returns everything you need to render an SEO-ready page — the contentHtml and pre-styled styledContentHtml body, metaTitle and metaDescription, the slug, target keywords, and a featured image URL where available.
Can I use the API with any framework or language?
Yes. It's a standard REST/JSON API, so anything that can make an authenticated HTTPS request — Node, PHP, Ruby, Python, Go, or a static-site build script — can pull your articles.