Viral Swipe File JSON API

Read-only JSON for niches, formats and videos, for signed-in accounts. A free account is enough.

Base URL: https://viralswipefile.com/api/v1. Machine-readable description: openapi.json (OpenAPI 3.1: one operationId per operation, security schemes, typed schemas).

Authentication

Every /api/v1 request needs an account, free or paid, sent one of two ways:

1. OAuth access token (agents and scripts): Authorization: Bearer <token>. No API key is issued; a client gets a token itself:

   • Discover the server from the 401's WWW-Authenticate: Bearer resource_metadata="https://viralswipefile.com/.well-known/oauth-protected-resource", or read the authorization server metadata.
   • Register a client at https://viralswipefile.com/api/auth/oauth2/register (dynamic client registration; public clients allowed).
   • Send the person to https://viralswipefile.com/api/auth/oauth2/authorize (authorization code with PKCE, S256, scope mcp:read, plus offline_access for a refresh token). They sign in by email link, code or Google and approve.
   • Exchange the code at https://viralswipefile.com/api/auth/oauth2/token.

   It is the same token MCP clients use: its audience is https://viralswipefile.com/api/mcp, and /api/mcp and /api/v1 both accept it.

2. Session cookie (the site and a signed-in browser): the Better Auth session set when you sign in.

Without credentials, or with a token that is expired, not for this site or not signed by it, the answer is 401 (code: unauthorized) with that WWW-Authenticate header. A token without mcp:read gets 403. Accounts are free: sign up.

What each plan gets

Every account, free included, gets the same listing: niche, format, platform, creator, offset (paging, up to 2,400), search, sort (viral | views | recent), time_period, viral_factor, content_type and creator_gender, up to 48 videos a page (24 by default).

What differs is the allowance. Connecting an AI agent is free on every plan, hooks and captions included, and any account can use the JSON API. Free: 50 questions a day (MCP tool calls and API requests together), counted from midnight UTC. Starter and Growth: no daily cap on agent questions; JSON API requests (bulk pulls) are 10,000 requests a month on Starter and 50,000 requests on Growth, counted from the 1st of each month (UTC). Every /api/v1 request counts, errors included; one the per-minute limit refuses does not. Past the allowance the answer is 402 (code: quota_exceeded), and resolution says when the count starts again.

See the plans.

Endpoints

• GET /api/v1/niches (listNiches): every niche with its slug and video count.
• GET /api/v1/formats (listFormats): every format with its slug and video count.
• GET /api/v1/videos (listVideos): videos filtered as above. Each has its hook, caption, creator, views, viral factor, engagement rate, niche, formats, posting date, cover image and page URL.

curl -H "Authorization: Bearer $TOKEN" "https://viralswipefile.com/api/v1/videos?niche=fitness&limit=5"

Rate limits

30 requests per 60 seconds per account. Every authenticated response carries RateLimit-Policy and RateLimit (IETF draft structured fields) and RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset. Over the limit you get 429 with Retry-After in seconds. Responses are Cache-Control: private, no-store.

Errors

Every error under /api/ is application/problem+json (RFC 9457): type, title, status, detail, instance, plus code (stable, branch on it) and resolution (what to do next). Codes: bad_request (400), unauthorized (401), quota_exceeded (402), forbidden (403), not_found (404), method_not_allowed (405), not_acceptable (406), rate_limited (429), internal_error (500). Unknown /api/ paths answer not_found in the same shape.

Other endpoints

• GET /api/health: liveness and the running build id. No account.
• /api/mcp: the MCP server (JSON-RPC, same OAuth token; any account, same allowance). See the MCP setup guide.
• /api/auth/*, /api/me and /api/creem/webhooks serve the site itself and are not a public API.

Questions: [email protected].