API reference

API overview

Base URL, versioning, authentication options, JSON conventions, and rate limits for the ViralSlides REST API.

1 min readLast updated May 17, 2026 Edit this page

Plan gating

Programmatic API access is available on Pro and Business plans. Free and Starter accounts can still use the dashboard, but API key authentication returns 403 PLAN_LACKS_API.

Base URL

text

https://api.viralslides.app/v0/api/v1

All API endpoints live under /v0/api/v1. The v0 prefix is the deployment generation; v1 is the public API version. Breaking changes will bump to /v0/api/v2 — minor additive changes won't.

Authentication

Two authentication schemes are supported. Both use the Authorization header.

API key (recommended for server-to-server): create a key on /api-keys. Format: vs_<random>. Send as Authorization: Bearer vs_xxx.
Session token (used by the dashboard): a short-lived JWT issued at login. Same header shape, but tokens expire in 24 hours.

Authenticated requestbash

curl https://api.viralslides.app/v0/api/v1/apps \
  -H "Authorization: Bearer vs_live_abc123..."

Response envelope

Every JSON response follows the same envelope. Success is the boolean indicator; the payload lives under body (single resource) or data (paginated collection).

Success — single resourcejson

{
  "success": true,
  "body": { /* resource */ }
}

Success — paginated listjson

{
  "success": true,
  "data": [ /* page items */ ],
  "page": 1,
  "limit": 50,
  "total": 137
}

Errorjson

{
  "success": false,
  "message": "QUOTA_EXCEEDED",
  "feature": "slideshows_per_month"
}

Rate limits

Per-organization, per-minute. Exceeding the limit returns 429 with a Retry-After header (seconds).

Plan	Requests / minute
Free	30
Starter	60
Pro	300
Business	1,200

Idempotency & retries

GET endpoints are always safe to retry. For POST endpoints that create resources (e.g. /apps/:id/slideshows), we recommend retrying on 5xx but not on 4xx. A 4xx means the request is structurally rejected and won't succeed without changes. A dedicated Idempotency-Key header lands in v1.1.