SuprSonic API

Key Features

Security-First Architecture

Consistent Response Format

RESTful Design

API Design Principles

Getting Started

Support

Welcome to the SuprSonic API documentation

Introduction

SuprSonic API Documentation

Get started with the SuprSonic API in minutes

Quickstart

Learn how to authenticate with the SuprSonic API

Authentication

Rate Limits

Pagination

Error Handling

Complete reference for the SuprSonic API endpoints

API Reference

Retrieve a paginated list of all accounts with their subscription status, plan entitlements, and content generation eligibility. Requires admin authentication. Provides all business logic needed for content generation systems.

List all accounts with subscription and entitlements

Retrieve a paginated list of articles with filtering and search options.
The articles returned depend on the authentication used:

**Authenticated Access:**
- **Admin API keys**: Returns articles from all accounts across the system
- **Account API keys**: Returns articles only from the account that owns the key

**Public Access** (from valid domains):
- **No authentication required** when accessing from verified domains (*.localhost, *.suprsonic.blog, *.suprsonic.app, or verified custom domains)
- Returns only **published articles** from the domain-associated account
- Status filtering is ignored for public access (always returns published only)


List articles

Create a new article. Currently requires admin API key for access.
- **Admin API keys**: Must provide account_id in request body, can create articles for any account

**Note**: In the future, we plan to implement scoped API keys that will allow account-specific keys to create articles for their own accounts.


Create a new article

Retrieve a single article by its UUID or slug. The article access is determined by the authentication:

**Authenticated Access:**
- **Admin API keys**: Can access any article from any account (including drafts, archived)
- **Account API keys**: Can only access articles from the account that owns the key

**Public Access** (from valid domains):
- **No authentication required** when accessing from verified domains (*.localhost, *.suprsonic.blog, *.suprsonic.app, or verified custom domains)
- Can only access **published articles** from the domain-associated account
- Draft, archived, or deleted articles return 404 for public access


Get a single article by ID or slug

Retrieve articles related to the specified article based on tag overlap and category matching. Returns article preview data without content.

**Sorting Logic:**
Related articles are sorted with sophisticated relevance scoring:
1. **Same Category + Tag Overlap**: Articles with matching category, sorted by tag overlap (descending), then publish date (descending)
2. **Different Category + Tag Overlap**: Articles with different category but tag overlap, sorted by tag overlap (descending), then publish date (descending)

Only articles with at least one overlapping tag are returned.

**Authenticated Access:**
- **Admin API keys**: Can get related articles for any article from any account
- **Account API keys**: Can only get related articles for articles from the account that owns the key

**Public Access** (from valid domains):
- **No authentication required** when accessing from verified domains (*.localhost, *.suprsonic.blog, *.suprsonic.app, or verified custom domains)
- Can only get related articles for **published articles** from the domain-associated account
- Only returns other **published articles** as related content


Get related articles

Retrieve a list of all article categories used by the account with their usage counts.
The categories returned depend on the authentication used:

**Authenticated Access:**
- **Admin API keys**: Returns categories from all accounts across the system
- **Account API keys**: Returns categories only from the account that owns the key

**Public Access** (from valid domains):
- **No authentication required** when accessing from verified domains (*.localhost, *.suprsonic.blog, *.suprsonic.app, or verified custom domains)
- Returns only categories from **published articles** from the domain-associated account


Get all categories

Retrieve all tags used in articles. The tags returned depend on the authentication used:

**Authenticated Access:**
- **Admin API keys**: Returns tags from all articles across all accounts in the system
- **Account API keys**: Returns tags only from articles belonging to the account that owns the key

**Public Access** (from valid domains):
- **No authentication required** when accessing from verified domains (*.localhost, *.suprsonic.blog, *.suprsonic.app, or verified custom domains)
- Returns tags only from **published articles** belonging to the domain-associated account
- Excludes tags from draft, archived, or deleted articles


Get all tags

Returns comprehensive account configuration including settings, branding, and customer personas for blog rendering and content generation

Get account settings, branding, and customer avatars

Generate SEO-optimized content including sitemaps, RSS feeds, robots.txt, and more for search engine optimization

Getting Started

Guides

​SuprSonic API

​Key Features

​API Design Principles

​Security-First Architecture

​Consistent Response Format

​RESTful Design

​Getting Started

​Support

SuprSonic API

Key Features

API Design Principles

Security-First Architecture

Consistent Response Format

RESTful Design

Getting Started

Support