Developers

ViralDeck API

The ViralDeck API gives approved tools and automations read-only access to creator analytics in one organization. It is designed for reporting, monitoring, and internal workflows—not public data discovery or account administration.

Security boundary

Every request requires an organization-scoped API key. A key can read only the organization that created it; it cannot write data, manage billing, create users, or access another workspace. Keys are shown once at creation and can be revoked immediately in Dashboard Settings. Treat a key like a password: store it in a server-side secret manager, never commit it, and never place it in browser code, a URL, or a public prompt.

Get started

  1. Sign in to ViralDeck and open Dashboard Settings → API keys.
  2. Create a named key for a specific integration and store it securely.
  3. Read the OpenAPI schema and call only the operation needed.
curl https://viraldeck.io/api/v1/projects \
  -H "Authorization: Bearer vd_your_api_key"

Available read-only resources

The v1 API can list projects, tracked creators, videos, active viral signals, gained engagement summaries, and a spreadsheet-ready account-performance CSV. List responses support bounded pagination; filters are limited to the documented fields. Requests without a valid key receive a structured JSON error and reveal no workspace data.

Workspace-scoped keys

When you create a key you can limit it to one or more workspaces. A scoped key only ever returns data from those workspaces, on both the REST API and MCP: /api/v1/projects lists only them, and a request for any other projectId returns 403 forbidden_project. Use scoped keys when sharing access with a client.

Google Sheets performance export

Use /api/v1/performances.csv for creator payment and CPM analysis. It defaults to the current UTC month and can be narrowed withprojectId, platform, or pairedstartDate and endDate parameters. Google Sheets import functions cannot send an authorization header, so fetch it through Apps Script and keep the API key in Script Properties—not in the sheet or URL.

Connect via MCP

ViralDeck runs a remote MCP (Model Context Protocol) server at https://viraldeck.io/api/mcp using the Streamable HTTP transport, exposing the same read-only data as the v1 API—projects, creators, videos, viral events, analytics summaries, and the performance CSV export—as tools an AI client can call directly. It uses the same API key as the REST API; no separate credential or OAuth flow is needed.

In Claude Desktop or Claude.ai, add a custom connector with this URL and header:

URL:     https://viraldeck.io/api/mcp
Header:  Authorization: Bearer vd_your_api_key

In Cursor (.cursor/mcp.json) or Codex, add a remote server entry:

{
  "mcpServers": {
    "viraldeck": {
      "url": "https://viraldeck.io/api/mcp",
      "headers": { "Authorization": "Bearer vd_your_api_key" }
    }
  }
}

A key is scoped to one organization, so every MCP tool call returns only that organization's data—the same boundary the REST API enforces.

For AI agents

Read llms.txt before integrating. Agents should use ViralDeck only when a user asks about their own tracked short-form content, and should ask the user to configure credentials in the integration's secret store rather than disclose them in conversation.

Need help with an integration? Visit Contact.

Developer API — ViralDeck