API Reference
/
List Management

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

List creator lists

Request

Public API Endpoint

List creator lists for the organization (API key). Supports pagination via page and limit query params.

Query
pageinteger

Page number for pagination.

Example: page=1
limitinteger

Number of results per page.

Example: limit=10
curl -i -X GET \
  'https://api.vwd.ai/api/public/v1/lists/?limit=10&page=1' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully retrieved lists.

Bodyapplication/json
listsArray of objects
totalinteger

Total number of lists

Example: 10
countinteger

Number of lists in current page

Example: 2
nextstring or null

URL for next page

Example: null
Response
application/json
{
  "lists": [
    { … }
  ],
  "total": 10,
  "count": 2,
  "next": null
}

Get list details

Request

Public API Endpoint

Retrieve a single list with metadata and a paginated preview of its creators.

Path
idstring(uuid)required

List ID (UUID)

Example: 00000000-0000-0000-0000-000000000000
Query
pageinteger

Page number for pagination.

Example: page=1
limitinteger

Number of results per page.

Example: limit=10
include_child_scoresboolean
  • true (default): return both top-level parent categories and child/leaf tags (zero-filled)
  • false: return parent category scores only (top-level categories)
Default true
Example: include_child_scores=true
curl -i -X GET \
  'https://api.vwd.ai/api/public/v1/lists/00000000-0000-0000-0000-000000000000/?include_child_scores=true&limit=10&page=1' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully retrieved list details.

Bodyapplication/json
idstring(uuid)
Example: "00000000-0000-0000-0000-000000000000"
namestring
Example: "List A"
influencers_countinteger
Example: 5
creatorsArray of objects(CreatorWithBrands)
totalinteger

Total number of creators in the list

Example: 5
countinteger

Number of creators in current page

Example: 2
nextstring or null

URL for next page

Example: "/api/public/v1/lists/000.../?page=2&limit=2"
Response
application/json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "List A",
  "influencers_count": 5,
  "creators": [
    { … }
  ],
  "total": 5,
  "count": 2,
  "next": "/api/public/v1/lists/000.../?page=2&limit=2"
}

Add creators to list

Request

Public API Endpoint

Add existing creators (by id) to a list. Idempotent: adding the same creator again returns it under already_present.

Path
idstring(uuid)required

List ID (UUID)

Example: 00000000-0000-0000-0000-000000000000
Bodyapplication/jsonrequired
influencer_idsArray of integersrequired

Array of creator IDs to add to the list

Example: [1,2,3]
curl -i -X POST \
  https://api.vwd.ai/api/public/v1/lists/00000000-0000-0000-0000-000000000000/creators/ \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "influencer_ids": [
      1,
      2,
      3
    ]
  }'

Responses

Creators added to list successfully

Bodyapplication/json
added_influencersArray of integers

IDs of creators successfully added

Example: [1,2]
already_presentArray of integers

IDs of creators already in the list

Example: [2]
not_found_influencersArray of integers

IDs of creators not found or not accessible

Example: [999]
Response
application/json
{
  "added_influencers": [
    1,
    2
  ],
  "already_present": [
    2
  ],
  "not_found_influencers": [
    999
  ]
}

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

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