API Reference

Votriz API Documentation

Build on top of Votriz with our REST API. JWT-authenticated, 160+ endpoints, same surface the dashboard uses.

Base URL: https://api.votriz.com

Authentication

All endpoints except /auth/login, /auth/register, and public marketing routes (/audit/free, /waitlist/join, /support/*) require a Bearer token. Log in to get one:

# 1. Get a token
curl -X POST https://api.votriz.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"..."}'

# Response: { "access_token": "...", "token_type": "bearer", "user": {...} }

# 2. Use the token
curl https://api.votriz.com/dashboard/overview \
  -H "Authorization: Bearer $TOKEN"

Access tokens are JWTs (15-minute lifetime). Refresh via POST /auth/refresh using the httpOnly refresh-token cookie set at login time (30-day lifetime).

Endpoint groups

The full OpenAPI schema with every request/response shape is live at api.votriz.com/docs (Swagger UI — try any call right from the browser).

Auth 8
Register, login, verify, refresh, logout, password reset, CSRF token, me.
Brands 14
CRUD, active brand, brand memory (voice profile, audience, etc.), logo upload.
Channels 13
Connect/disconnect each platform (OAuth callbacks), list, status, validate.
Content 10
Generate, queue, published, approve, reject, edit, regenerate image/video.
Email 28
Campaigns, templates, subscribers, automations, lead gen, analytics, webhook.
Growth / SEO 22
SEO audits, keywords, clusters, backlinks, technical issues, traffic, trends, experiments.
Monitoring 6
Mentions, sentiment, incidents, approve/dismiss crisis responses.
Community 3
Inbox, conversation opportunities, influencer tracking.
Analytics 5
Overview, by-channel, by-post, engagement rate, time series.
Video 6
Generate, render, templates, jobs, thumbnails, inspiration.
Billing 5
Checkout, status, cancel, update payment method, invoices.
Dashboard 4
Overview, badges, presence score, recent activity.

Rate limits

Per-token rate limits by tier:

AI generation endpoints (/email/generate, /content/generate, /video/generate) have separate per-day quotas by tier — see the Help Center.

Errors

All errors use standard HTTP codes + a JSON body shaped {"detail": "message"}. 401 = bad/expired token. 403 = tier insufficient. 422 = body validation. 429 = rate limit (Retry-After header set). 5xx = our problem — retry with backoff.

Webhooks

Outbound webhooks for campaign events (opened, clicked, bounced), content approvals, and incidents. Configure at Settings → Integrations. HMAC-signed with your webhook secret; see X-Votriz-Signature header format in the full Swagger docs.