API Reference
REST API for the AI SNS · Social Studio publishing platform. All responses are JSON unless noted. This page is generated from the server source and reflects the deployed build.
Auth & conventions
How authentication, roles, plan limits and credits work across every route.
POST /api/auth/register with {email, password, workspace?} creates a user + workspace (you become owner) and returns {token, workspace_id}. POST /api/auth/login with {email, password, workspace_id?} returns {token, workspace_id}. The token is a self-signed HS256 JWT (30-day TTL) carrying {uid, ws, email}. There is no refresh endpoint — re-login when it expires.
curl -H "Authorization: Bearer <token>" \
https://<host>/api/posts
Everything under /api passes through requireAuth, which resolves your workspace, user id and role. Auth resolves in order: (1) legacy API_TOKEN env match → owner on workspace 1; (2) a valid JWT (membership checked); (3) open dev/demo mode.
API_TOKEN is unset and OPEN_MODE !== "0", unauthenticated /api requests are accepted as an owner on the default workspace. Set OPEN_MODE=0 (or an API_TOKEN) to require real auth in production.
AUTH routes need any valid session. WRITE routes additionally require canWrite — only owner and editor (a viewer/client gets 403 {error:"read-only role"}). ADMIN needs the x-admin-secret header; CRON needs x-cron-secret; PUBLIC needs no bearer (a token/id in the path is the credential).
Some writes call checkLimit(ws, kind) for post/ai/account. On breach:
402 { "error":"limit_reached", "kind":"posts|ai_units|accounts", "limit":30, "upgrade":true }
Monthly tiers (lib/meter.js): free {posts:30, ai_units:100, accounts:2} · pro {500, 3000, 10} · agency {5000, 20000, 50}.
A separate ledger (lib/billing.js). AI actions spend credits per a COST map (draft/hashtags/… = 1, image/image-ref = 5). Credits are soft by default (tracked, never block) unless ENFORCE_CREDITS=1. Only /api/influencers/analyze hard-checks credits (402 out_of_credits).
server.js + lib/*.js. Auth badges: PUBLIC AUTH WRITE ADMIN CRON.