VwD API Support
License
External API for accessing VwD creators data.
https://api.vwd.ai/api/public/v1/
https://apidocs.vwd.ai/_mock/apis/
https://api.vwd.ai/api/public/v1/creators/
https://apidocs.vwd.ai/_mock/apis/creators/
curl -i -X GET \
'https://api.vwd.ai/api/public/v1/creators/?include_child_scores=false&limit=10&page=1' \
-H 'Authorization: YOUR_API_KEY_HERE'{ "creators": [ { … } ], "total": 100, "count": 10, "next": "https://api.vwd.ai/api/public/v1/creators/?page=2&limit=10" }
Public API Endpoint
Add creators either one at a time (single JSON object) or in bulk (object with an items array). Tokens are debited per creator according to the scan_type tier (default scan_full = 3 tokens) plus monitoring (+1 token) if enabled.
Bulk semantics — all-or-nothing at the budget gate: if the aggregate cost of all billable rows exceeds your token balance, the whole request returns 402 and nothing is created or charged. After the gate, per-row save failures (rare race conditions) appear as status: "failed" in the results and do not consume tokens; the batch continues.
Append ?dry_run=true to preview the token cost and outcome without side effects (no creator created, no tokens debited). Validation still runs.
Re-adding a creator the same org previously hard-deleted restores the archived scan purchase and is not charged (rebind). Bulk ?dry_run=true excludes predicted rebinds from the aggregate cost — the live debit matches.
Creator display name. Letters, digits, spaces, -, ., & only — no emoji/symbols. Trimmed; empty/whitespace → 400.
Social media platform. google_news/reddit are system-created and rejected on input; onlyfans is output-only.
Initial scan tier slug. Determines history coverage and token cost. Default scan_full (3 tokens, full history). Valid values are the active slugs returned by GET /scan-catalog/ → initial_scans[] (seeded defaults: scan_1y / scan_2y / scan_full). Invalid slug → 400.
Enable monitoring at creation (+1 token, see GET /scan-catalog/ → monitoring.token_cost). Saves a follow-up call to /monitor/.
https://api.vwd.ai/api/public/v1/creators/
https://apidocs.vwd.ai/_mock/apis/creators/
curl -i -X POST \
'https://api.vwd.ai/api/public/v1/creators/?dry_run=false' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"name": "Jane Doe",
"social_profiles": [
{
"platform": "instagram",
"profile_url": "https://instagram.com/janedoe"
}
],
"scan_type": "scan_1y",
"monitoring": true,
"confirm_duplicate": false
}'Bulk request processed, or dry-run preview returned. The bulk live response carries a results array (per-row outcomes) and a summary. The dry-run response (?dry_run=true, on single or bulk) carries cost + would-succeed.
Bulk create response (HTTP 200 even with row failures). Each row reports its outcome via status; the summary aggregates counts. summary.failed = requested − created (so it sums both "invalid" and "failed" rows). Note: the legacy top-level quota object and the quota_exceeded row status were removed when the token model launched — budget failures now return 402 at the request level (not per-row).
{ "results": [ { … }, { … }, { … }, { … } ], "summary": { "requested": 4, "valid": 2, "created": 1, "failed": 3 } }
Public API Endpoint
Enables monitoring for an existing creator in your organization. Idempotent: calling again when already enabled still returns is_monitored: true. Charges the per-cycle monitoring cost from GET /scan-catalog/ → monitoring.token_cost on first enable.
Append ?dry_run=true to preview cost without enabling monitoring.
https://api.vwd.ai/api/public/v1/creators/{id}/monitor/
https://apidocs.vwd.ai/_mock/apis/creators/{id}/monitor/
curl -i -X POST \
'https://api.vwd.ai/api/public/v1/creators/123/monitor/?dry_run=false' \
-H 'Authorization: YOUR_API_KEY_HERE'{ "is_monitored": true }
Token-budget discovery and scan-catalog endpoints for the prepaid token model that powers creator scans, re-scans, and monitoring.
Prepaid tokens. Billable actions (new scans via POST /creators/, re-scans via POST /creators/{id}/rescan/, monitoring via POST /creators/{id}/monitor/) consume tokens from your organization's API budget. Read the current balance with GET /account/usage/. Token purchasing happens outside the API — contact your account manager to top up.
Scan tiers. A scan tier determines how much creator history is analyzed and the token cost. Initial-scan tiers (scan_1y / scan_2y / scan_full) are used on creator create; re-scan tiers (rescan_lite / rescan_mild / rescan_full) refresh or deepen an existing creator. Costs are admin-configurable — always read GET /scan-catalog/ for live values instead of hardcoding tiers.
Data visibility windows. Historical sub-resources (posts, timeline, brands, compliance) for newly-added creators are scoped to the time range covered by the scan tier purchased. The visibility{} block on GET /creators/{id}/ tells you the exact window and whether a deeper scan is available. Creators added before the token-model launch (2026-05-30) remain unrestricted.
Previewing cost. Append ?dry_run=true on POST /creators/ (single & bulk) or POST /creators/{id}/monitor/ to preview the token cost and outcome without making any change or debiting tokens. Validation still runs.
See the PLG launch changelog post for the full migration guide.