API Reference

The whiz.pub REST API is available at /api/v1. All requests and responses use JSON.

Interactive API documentation (ReDoc) is available at whiz.pub/api/v1.

Authentication

Most endpoints require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You receive an API key when you sign up (via the web dashboard, CLI, or API). You can also find it on your settings page at /app/settings.

Auth Levels

Level	Description	Endpoints
Public	No authentication required	POST /signup, POST /forgot-password, POST /reset-password, GET /health
Pre-verified	Requires API key, email verification not yet completed	POST /verify-email, POST /resend-verification
Verified	Requires API key with verified email	All other endpoints

New accounts must verify their email before they can publish posts, manage domains, or update themes.

Endpoints

Method	Path	Auth Level	Description
POST	/api/v1/signup	Public	Create an account and blog
POST	/api/v1/verify-email	Pre-verified	Verify email with code
POST	/api/v1/resend-verification	Pre-verified	Resend verification code
POST	/api/v1/forgot-password	Public	Request a password reset email
POST	/api/v1/reset-password	Public	Reset password with token
POST	/api/v1/posts	Verified	Create or update a post (upsert by slug)
GET	/api/v1/posts	Verified	List posts (?limit= and ?offset=)
GET	/api/v1/posts/:slug	Verified	Get a specific post
DELETE	/api/v1/posts/:slug	Verified	Delete a post
POST	/api/v1/domains	Verified	Add a custom domain
DELETE	/api/v1/domains	Verified	Remove custom domain
POST	/api/v1/domains/:domain/verify	Verified	Verify domain DNS records
GET	/api/v1/theme	Verified	Get theme and appearance settings
PUT	/api/v1/theme	Verified	Update theme, fonts, custom CSS
PUT	/api/v1/headless	Verified	Enable or disable headless mode
GET	/health	Public	Health check

Rate Limiting

The signup endpoint is rate-limited to 5 requests per minute per IP address. Other endpoints are not currently rate-limited but may be in the future.

Error Format

Errors return an appropriate HTTP status code with a JSON body:

{
  "error": "email already registered"
}

Common status codes:

Code	Meaning
400	Invalid request body or parameters
401	Missing or invalid API key
403	Email not verified (for verified-only endpoints)
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Examples

Create a post

curl -X POST https://whiz.pub/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Post",
    "slug": "my-first-post",
    "content": "Hello, world! This is **markdown**.",
    "tags": ["intro", "blogging"],
    "status": "published",
    "summary": "A short excerpt for the index and RSS feed.",
    "featured_image": "https://example.com/social.jpg",
    "pinned": false
  }'

The post endpoint performs an upsert — if a post with the given slug already exists, it is updated.

Optional post metadata:

• summary: custom excerpt. If omitted, whiz generates one from the content.
• featured_image: HTTPS image URL for post-level social previews.
• pinned: when true, the post appears before regular posts on the public index.

List posts

curl https://whiz.pub/api/v1/posts?limit=10&offset=0 \
  -H "Authorization: Bearer YOUR_API_KEY"

Get a single post

curl https://whiz.pub/api/v1/posts/my-first-post \
  -H "Authorization: Bearer YOUR_API_KEY"

Public blogs also expose reader-facing discovery endpoints:

• /rss.xml: RSS feed for published posts.
• /tag/{tag}: HTML index of published posts with a matching tag.

Delete a post

curl -X DELETE https://whiz.pub/api/v1/posts/my-first-post \
  -H "Authorization: Bearer YOUR_API_KEY"

Sign up

curl -X POST https://whiz.pub/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password",
    "subdomain": "yourname"
  }'

The response includes your API key. Use it in subsequent requests.

Enable headless mode

curl -X PUT https://whiz.pub/api/v1/headless \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

When headless mode is enabled, the blog's public pages (subdomain, sitemap, robots.txt, etc.) return 404. The API, CLI, and MCP continue to work normally. Your subdomain remains reserved. Headless mode cannot be enabled while a custom domain is configured — remove the domain first.