Intelligent CreativeNewsroomResourcesAbout UsHelp
Documentation

Quick Start

The fastest path through each major capability. All requests require Authorization: Bearer <api-key>.

0. Find your workspaceId

Do this first. GET /v1/organization returns only the organization id and name — it does not list
workspaces, despite what some guides imply. The endpoint you want is GET /v1/workspaces.

curl -H "Authorization: Bearer $API_KEY" \
  https://public-api.vidmob.com/v1/workspaces
# → { "status": "OK", "result": [ { "id": 45914, "name": "Acme Inc." }, ... ],
#     "pagination": { "offset": 0, "perPage": 10, "nextOffset": 10, "totalSize": 73 } }

1. Score an external asset

# Step 1 — register the media (returns a uniqueId)
curl -X POST https://public-api.vidmob.com/v1/media \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "spring-15s-vertical-v1",
    "version": "1.0",
    "url": "https://your-cdn.com/creative.mp4",
    "workspaceId": 45914,
    "channels": ["META", "ADWORDS", "TIKTOK"]
  }'
# → 201 { "status": "OK", "result": { "uniqueId": "8576725c-..." } }

# Step 2 — poll until status is terminal
curl -H "Authorization: Bearer $API_KEY" \
  https://public-api.vidmob.com/v1/media/8576725c-.../status
# → { "result": { "status": "COMPLETE", ... } }

# Step 3 — fetch scores (note: channel keys come back as FACEBOOK / TWITTER)
curl -H "Authorization: Bearer $API_KEY" \
  "https://public-api.vidmob.com/v1/scoring/media/8576725c-.../scores?format=detail"

A 10-second video submitted with no workspaceId reached COMPLETE in about 8 minutes in testing.

2. Tag an asset (Aperture)

# Submit one or more creatives for AI tagging
curl -X POST https://public-api.vidmob.com/v1/media/aperture \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "creatives": [{ "id": "creative-001", "url": "https://your-cdn.com/creative-001.mp4" }],
    "clientTags": { "brand": "acme" }
  }'
# → 201 { "status": "OK", "result": { "jobId": "07fd81fc-...", "status": "QUEUED", ... } }

# Poll the job until terminal, then download the CSV report
curl -H "Authorization: Bearer $API_KEY" \
  https://public-api.vidmob.com/v1/media/aperture/07fd81fc-...
# → { "result": { "status": "COMPLETED", "downloadUrlCsv": "https://...s3...", ... } }

Results are CSV only. There is no JSON report. One 10-second video took about 17 minutes and produced
759 tag rows. See creative_tags_api_guide_v3.md for the full report format.

3. Discover scoring guidelines

curl -X POST https://public-api.vidmob.com/v1/scoring/criteria/metadata \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "workspaces": [45914] }'
# → 201 (yes, 201 for a read-only lookup)

Submitting media for analysis is asynchronous — you submit, then poll. This applies to POST /v1/media
(scoring) and POST /v1/media/aperture (tagging). All other endpoints are synchronous.

Updated about 1 month ago

What’s Next

The fastest path through each major capability. All requests require Authorization: Bearer <api-key>.

1. Score an external asset

# Step 1 — register the media (returns a uniqueId)
curl -X POST https://public-api.vidmob.com/v1/media \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "spring-15s-vertical-v1",
    "version": "1.0",
    "url": "https://your-cdn.com/creative.mp4",
    "workspaceId": 45914,
    "channels": ["META", "ADWORDS", "TIKTOK"]
  }'
# → { "status": "OK", "result": { "uniqueId": "8576725c-..." } }

# Step 2 — poll until status is COMPLETE (every 10–15 minutes)
curl -H "Authorization: Bearer $API_KEY" \
  https://public-api.vidmob.com/v1/media/8576725c-.../status
# → { "result": { "status": "COMPLETE", ... } }

# Step 3 — fetch scores
curl -H "Authorization: Bearer $API_KEY" \
  "https://public-api.vidmob.com/v1/scoring/media/8576725c-.../scores?format=detail"

2. Tag an asset (Aperture)

# Submit one or more creatives for AI tagging
curl -X POST https://public-api.vidmob.com/v1/media/aperture \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "creatives": [{ "id": "creative-001", "url": "https://your-cdn.com/creative-001.mp4" }],
    "clientTags": { "brand": "acme" }
  }'
# → { "jobId": "07fd81fc-...", "status": "QUEUED", ... }

# Poll the job until it completes, then download the tag JSON
curl -H "Authorization: Bearer $API_KEY" \
  https://public-api.vidmob.com/v1/media/aperture/07fd81fc-...
# → { "status": "COMPLETED", "downloadUrlJSON": "https://...", ... }

Quick Start

curl -X POST https://public-api.vidmob.com/v1/scoring/criteria/metadata \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "workspaces": [45914] }'

Note: Scoring is asynchronous everywhere — you submit, then poll. Plan for media to take time to process; polling intervals of 10–15 minutes are appropriate.

Did this page help you?