Authentication

The ViralNote API uses bearer tokens. The same endpoints accept two equivalent forms — a Firebase user ID token (for first-party clients) or a long-lived API key (for backend integrations and agents).

Get an API key

1. Sign in to ViralNote and open Settings → API keys.
2. Click Create key, give it a label (e.g. "Zapier", "MCP server"), and pick scopes.
3. Copy the key immediately — it's shown once and never displayed again. Store it in your secret manager / .env file.

Send a request

Send the key as the x-api-key header (preferred), or as a bearer token in Authorization.

# Using x-api-key header
curl https://viralnote.app/api/v1/posts \
  -H "x-api-key: $VIRALNOTE_API_KEY"

# Using Authorization header (equivalent)
curl https://viralnote.app/api/v1/posts \
  -H "Authorization: Bearer $VIRALNOTE_API_KEY"

Scopes

Each key carries a set of scopes that constrain what it can do. Request only what you need.

Scope	Grants
posts:read	List, read, and search posts. Read analytics and publish history.
posts:write	Create, update, delete, and publish posts. Upload and import media.
webhooks:read	List webhook subscriptions.
webhooks:write	Create, update, and delete webhook subscriptions.

Rate limits

Default rate limit is 60 requests per minute per API key, with route-specific caps on heavier endpoints (e.g. /media upload at 20/min, /media/import at 10/min). A custom per-minute cap can be set on a key when you create it.

Responses that exceed the limit return 429 with a Retry-After header. Back off and retry.

Errors

All errors return a consistent JSON envelope:

{
  "requestId": "abc123",
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Include the requestId in any support correspondence — it lets us look up the exact server-side trace.