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 /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, 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/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
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"
  }'

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

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"

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": "[email protected]",
    "password": "your-password",
    "subdomain": "yourname"
  }'

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