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
Your API base URL is shown when you create an API token in Settings → Integrations → API Tokens.
https://your-deployment.convex.siteStore 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://your-convex-url.convex.site/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://your-convex-url.convex.site/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://your-convex-url.convex.site/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://your-convex-url.convex.site/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.