Creator API

Read your workspace's Amazon earnings, orders, product performance, stores, brand deals and storefront, look back at their history, and run Findr searches on the workspace's Findr credits, over HTTPS. Requests and responses are JSON. AI assistants use the same key through MCP.

Authentication

Every request needs a workspace API key, and the workspace needs the API & MCP access add-on. Workspace owners create keys in the Viral Vue web app under Workspace settings > API & MCP and accept the API usage terms for each new key. The owner can reveal a key there again later, so a lost key does not need replacing. Send the key as a bearer token:

Authorization: Bearer vvk_...

Anyone with the key can read the workspace's data and spend its Findr credits. Keep it on your server and never put it in browser or mobile app code.

Requests

Send requests to . Paths under /user/v1 describe the person behind the key; everything else is under /workspace/v1. This request returns the account behind the key, which is the workspace owner:

curl /user/v1/me \
  -H "Authorization: Bearer $VIRALVUE_API_KEY"

GET /workspace/v1/info returns the workspace itself: its plan, add-ons, linked storefront, features and Findr credits.

Features and plans

The storefront and Findr endpoints belong to features of the web app and need them exactly as the web app pages do: Storefront for /workspace/v1/storefront, including its placement history, Product Vue (Products) for /workspace/v1/amazon/product-history, and ASIN Findr, Product Findr, Campaign Findr or Campaign Checker for /workspace/v1/findr. They are on the Professional plan by default. A key has the access of the workspace owner. features of /workspace/v1/info lists every feature with whether the workspace has it; without it a request fails with 403 workspace.feature_required, and details.reason says why.

Findr credits

The Findr endpoints spend the workspace's Findr credits, the same credits as the Findr pages of the web app, at the same prices. Credits are reserved before a search and refunded when it fails; without enough credits the request fails with 402 findr.insufficient_credits and spends nothing. Each response reports the credits it spent and the balance left:

{"credits": {"charged": 10, "balance": {"totalCreditsRemaining": 328, "resetsAt": 1790000000000}}}

GET /workspace/v1/findr/credits returns the balance, the cost of each feature and the usage per feature without spending anything.

History

The history endpoints read a window of UTC days, set with from and to (YYYY-MM-DD). Without them the window is the last 90 days up to today; it covers at most 366 days. Each response repeats the window it read in window.

Placement history counts video days: each storefront video counts once per day, by its last placement that day. amazon.com keeps every day; the other marketplaces keep the last 14 days (window.retentionDays), so older days read as zero. A null earnings source means no summary row for that day, not zero earnings.

curl "/workspace/v1/storefront/placement-history?asins=B0TRAIL001&from=2026-07-01&to=2026-09-27" \
  -H "Authorization: Bearer $VIRALVUE_API_KEY"

Pagination

Lists return one page of items in data and describe the page in pagination. Set the page size with limit, from 1 to 500 and 100 by default, and skip items with offset. Request the next page while hasMore is true.

{"data": [], "pagination": {"limit": 100, "offset": 0, "hasMore": true}}

Errors

Failed requests return an HTTP error status and a JSON body with a stable code. Quote the requestId when you contact support.

Rate limits

Each API key has its own budget, by default 120 requests per minute, and all keys of a workspace together are capped, by default 240 per minute. Limits for your workspace can differ. Product, Findr, video, order, Campaign Checker and history endpoints have additional per-key and per-workspace budgets listed with each endpoint; the history endpoints share one of 30 requests per minute per key and 60 per workspace. Staff may also set a per-minute limit for a single endpoint. MCP calls count against the same budgets as the matching endpoints; send one tool call per request (JSON-RPC batches that contain tool calls are rejected with error -32600). Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.

Further requests get a 429 response whose Retry-After header gives the seconds to wait. Many requests with unknown keys from one IP address are answered with 429 too.

Marketplaces

Amazon endpoints read one marketplace at a time, set with region: us for amazon.com, the default, or uk, ca, au, sg or de.