Skip to main content

API Overview

ViralSync exposes a REST API over HTTPS. All requests require an API key and return JSON responses. Jobs are asynchronous — you submit work and receive a jobId to track progress.

API Access Required

The REST API requires a Pro plan or higher. Free-plan users can render through the visual editor. See Plans →

Base URL​

https://api.viralsync.io

All endpoints are relative to this base URL. Example: GET /v1/jobs → GET https://api.viralsync.io/v1/jobs.

Authentication​

All requests must include your API key in the x-api-key header:

curl -H "x-api-key: vs_prod_YOUR_API_KEY" https://api.viralsync.io/v1/me

API keys are created in Dashboard → Settings → API Keys. See Authentication →

Request format​

  • All request bodies must be JSON (Content-Type: application/json)
  • Query parameters use standard URL encoding

Response format​

All responses are JSON. Successful responses return the requested data directly. Error responses always include error and code fields.

Success (200/202):

{ "jobId": "job_a1b2c3d4e5f6", "status": "queued" }

Error (4xx/5xx):

{ "error": "Monthly render quota exceeded.", "code": "RENDER_QUOTA_EXCEEDED" }

Versioning​

The current API version is v1. The version is included in every endpoint path (/v1/...).

Breaking changes will be released under a new version prefix (/v2/...) with a migration guide and a deprecation period. Non-breaking additions (new optional fields, new endpoints) are made to the current version without notice.

Pagination​

List endpoints (GET /v1/jobs) use cursor-based pagination:

ParameterDescription
limitNumber of items per page (1–100, default 25)
cursorOpaque string from the previous page's nextCursor
# First page
curl -H "x-api-key: vs_prod_..." "https://api.viralsync.io/v1/jobs?limit=10"

# Next page
curl -H "x-api-key: vs_prod_..." "https://api.viralsync.io/v1/jobs?limit=10&cursor=eyJsYXN0SWQiOi..."

When nextCursor is null in the response, you have reached the last page.

Rate limits​

All plans share a limit of 120 requests per 60-second sliding window per API key. When exceeded, the API returns 429 Too Many Requests with a Retry-After header.

See Rate Limits →

Endpoint reference​

MethodPathDescription
POST/v1/render/jobsSubmit a render job
GET/v1/jobsList all jobs
GET/v1/jobs/{jobId}Get a specific job
GET/v1/jobs/{jobId}/progressStream real-time progress (SSE)
POST/v1/jobs/{jobId}/cancelCancel a running job
DELETE/v1/jobs/{jobId}Delete a terminal job
GET/v1/meCurrent user info (userId, plan, email)
GET/v1/usageCurrent render minute usage and limits

Quick navigation​