API Reference
/
Account & Tokens

VwD External API (1.0.0)

External API for accessing VwD creators data.

Download OpenAPI description
index.json
index.yaml
Overview
VwD API Support

support@vwd.ai

License

MIT

Languages
Servers
VwD Production API Server

https://api.vwd.ai/api/public/v1/

Mock server

https://apidocs.vwd.ai/_mock/apis/

Creator Management

Endpoints related to creators information and searches.

Operations

Brand Management

Endpoints for brand search and management.

Operations

List Management

Endpoints for managing creator lists.

Operations

Search

Full-text search endpoints powered by Elasticsearch.

Operations

Account & Tokens

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.

Operations

Get token budget

Request

Public API Endpoint

Discover the API token budget for your organization: lifetime limit, lifetime usage, remaining balance, disabled state, and budget-state band (NORMAL / LOW / CRITICAL / EMPTY).

Token purchasing happens outside the API — contact your account manager to top up.

curl -i -X GET \
  https://api.vwd.ai/api/public/v1/account/usage/ \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Token budget snapshot.

Bodyapplication/json
api_token_limitinteger or null

Lifetime API token limit. null = unlimited; 0 = API disabled.

Example: 5000
api_tokens_usedinteger

Lifetime API-channel token debits. UI/system usage is not counted.

Example: 320
api_tokens_remaininginteger or null

null if unlimited; otherwise max(limit − used, 0).

Example: 4680
api_disabledboolean

true if api_token_limit == 0.

Example: false
statestring

Budget-state band based on remaining balance vs. configured thresholds: EMPTY (= 0), CRITICAL (≤ critical threshold), LOW (≤ low threshold), else NORMAL.

Enum"NORMAL""LOW""CRITICAL""EMPTY"
Example: "NORMAL"
Response
application/json
{
  "api_token_limit": 5000,
  "api_tokens_used": 320,
  "api_tokens_remaining": 4680,
  "api_disabled": false,
  "state": "NORMAL"
}

List scan tiers and costs

Request

Public API Endpoint

The live, authoritative list of scan_type values and their token costs. Use this to populate UI pickers and to verify costs before adding creators or re-scanning. Values are admin-editable — always read this endpoint instead of hardcoding tiers.

curl -i -X GET \
  https://api.vwd.ai/api/public/v1/scan-catalog/ \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Scan catalog.

Bodyapplication/json
initial_scansArray of objects(ScanCatalogItem)

Tiers valid as scan_type on POST /creators/. Ordered shallow → deep.

rescansArray of objects(ScanCatalogItem)

Tiers valid as scan_type on POST /creators/{id}/rescan/.

monitoringobject
Response
application/json
{
  "initial_scans": [
    { … },
    { … },
    { … }
  ],
  "rescans": [
    { … },
    { … },
    { … }
  ],
  "monitoring": {
    "token_cost": 1
  }
}

Content Analysis

Endpoints for retrieving creators posts with labels.

Operations

Brand Mentions

Endpoints for creators posts and timelines related to brands.

Operations

Compliance Monitoring

Endpoints for creators compliance data.

Operations