API Reference

Complete endpoint reference with copyable curl examples for CreatiVault Open API.

💡

Base URL: https://{host}/openapi/v1/ — All requests use POST method with JSON body.

Authentication

All requests require X-API-Key and X-User-Identity headers (email address).

HTTP Headers

X-API-Key: your_api_key_here
X-User-Identity: user@example.com
Content-Type: application/json

Endpoints

Endpoint	Method	Description	Required Scope
/v1/creators/tiktok/search	POST	Search TikTok creators	creators:tiktok:search
/v1/creators/youtube/search	POST	Search YouTube creators	creators:youtube:search
/v1/creators/instagram/search	POST	Search Instagram creators	creators:instagram:search
/v1/creators/lookalike	POST	Find similar creators (lookalike)	-
/v1/collection/tasks/submit	POST	Submit link/username collection task	collection:submit
/v1/collection/tasks/keyword-submit	POST	Submit keyword collection task	collection:keyword-submit
/v1/collection/tasks/status	POST	Query task status	collection:status
/v1/collection/tasks/data	POST	Get collected data (paginated)	collection:data
/v1/collection/tasks/export	POST	Export task data to file	collection:export
/v1/files/download-url	POST	Get file download URL	files:download
/v1/webhook/verify	POST	Verify webhook connectivity	Public (no auth)

Response Structure

All endpoints return a unified JSON structure with success, data, error, and meta fields.

Response Structure

{
  "success": true,
  "data": { ... },
  "error": null,
  "meta": {
    "request_id": "req_abc123",
    "page": 1,
    "size": 50,
    "total": 1200,
    "quota_remaining": -1,
    "service_level": "S2",
    "credits_consumed": 60
  }
}

Search Creators

Search creators with keyword and filters. The service_level parameter controls which fields are returned (S1/S2/S3).

TikTok

curl — POST /v1/creators/tiktok/search

curl -X POST "https://{host}/openapi/v1/creators/tiktok/search" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-User-Identity: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "beauty",
    "country_code": "US",
    "followers_cnt_gte": 10000,
    "page": 1,
    "size": 20,
    "sort_field": "followers_cnt",
    "sort_order": "desc",
    "service_level": "S2",
    "lang": "en"
  }'

YouTube

curl — POST /v1/creators/youtube/search

curl -X POST "https://{host}/openapi/v1/creators/youtube/search" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-User-Identity: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "US",
    "followers_cnt_gte": 50000,
    "page": 1,
    "size": 20,
    "sort_order": "desc",
    "service_level": "S2",
    "lang": "en"
  }'

Instagram

curl — POST /v1/creators/instagram/search

curl -X POST "https://{host}/openapi/v1/creators/instagram/search" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-User-Identity: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "US",
    "followers_cnt_gte": 10000,
    "is_product_kol": true,
    "page": 1,
    "size": 20,
    "service_level": "S2"
  }'

Collection Tasks

Link Collection (LINK_BATCH)

curl — POST /v1/collection/tasks/submit (LINK_BATCH)

curl -X POST "https://{host}/openapi/v1/collection/tasks/submit" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-User-Identity: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "LINK_BATCH",
    "platform": "tiktok",
    "values": [
      "https://www.tiktok.com/@creator1",
      "https://www.tiktok.com/@creator2"
    ],
    "task_name": "Q1 Creator Collection",
    "webhook_url": "https://your-server.com/webhook/collection"
  }'

Username Collection (FILE_UPLOAD)

curl — POST /v1/collection/tasks/submit (FILE_UPLOAD)

curl -X POST "https://{host}/openapi/v1/collection/tasks/submit" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-User-Identity: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "FILE_UPLOAD",
    "platform": "tiktok",
    "values": ["creator1", "creator2", "creator3"],
    "task_name": "Username Batch Collection"
  }'

Keyword Collection

curl — POST /v1/collection/tasks/keyword-submit

curl -X POST "https://{host}/openapi/v1/collection/tasks/keyword-submit" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-User-Identity: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "tiktok",
    "keywords": ["beauty tips", "skincare routine"],
    "task_name": "Keyword Collection",
    "webhook_url": "https://your-server.com/webhook/collection"
  }'

Query Task Status

curl — POST /v1/collection/tasks/status

curl -X POST "https://{host}/openapi/v1/collection/tasks/status" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-User-Identity: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "task_20260315_abc123"
  }'

Get Collected Data

curl — POST /v1/collection/tasks/data

curl -X POST "https://{host}/openapi/v1/collection/tasks/data" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-User-Identity: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "task_20260315_abc123",
    "page": 1,
    "size": 20
  }'

Export Data

curl — POST /v1/collection/tasks/export

curl -X POST "https://{host}/openapi/v1/collection/tasks/export" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-User-Identity: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "task_20260315_abc123",
    "format": "xlsx"
  }'

Get Download URL

curl — POST /v1/files/download-url

curl -X POST "https://{host}/openapi/v1/files/download-url" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
  }'

Similar Creators (Lookalike)

Find similar creators based on a seed creator. Supports cross-platform search with username or profile URL input.

curl — POST /v1/creators/lookalike

curl -X POST "https://{host}/openapi/v1/creators/lookalike" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-User-Identity: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "creator_demo",
    "platform": "tiktok",
    "target_region": "US",
    "limit": 10,
    "follower_min": 10000,
    "lang": "en"
  }'

Webhook Verification

Verify webhook URL connectivity before submitting collection tasks. This is a public endpoint — no authentication required.

curl — POST /v1/webhook/verify

curl -X POST "https://{host}/openapi/v1/webhook/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge": "test_connectivity_12345"
  }'

Webhook Callbacks

When a collection task completes, the system sends a POST callback to your webhook_url with HMAC-SHA256 signature verification.

Webhook Payload

{
  "event": "collection.completed",
  "task_id": "task_20260315_abc123",
  "task_type": "LINK_BATCH",
  "status": "completed",
  "total": 2,
  "completed": 2,
  "failed": 0,
  "timestamp": "2026-03-15T10:45:00Z"
}

💡

Webhook retries up to 3 times (10s, 30s, 90s intervals). Your endpoint must use HTTPS and respond within 5 seconds.