Overview

Vidmob is a Creative Data Platform that connects creative production with performance outcomes. The Vidmob Public API gives you programmatic access to two core capabilities: Creative Scoring and Creative Aperture. Together, they let you evaluate creative assets against brand and platform guidelines, annotate them with detected visual elements, and build feedback loops between creative decisions and performance data.

Base URL: https://public-api.vidmob.com/v1

The Two APIs

Creative Scoring API

Submit media assets for evaluation against a configured set of guidelines. Scoring is asynchronous — you submit an asset, poll until processing completes, then retrieve a structured result showing how the asset performed against each guideline across one or more advertising channels.

Results include:

• A score (weighted aggregate, 0.0–1.0) and adherencePercent (simple pass rate, 0.0–1.0) per channel
• A per-guideline breakdown: PASS, FAIL, NOT_APPLICABLE, NO_DATA, or a specific NO_DATA_* code
• Pass/fail counts and applicable guideline totals

Scoring is built around Scorecards — named collections of guidelines configured per workspace. Guidelines can be scoped org-wide or workspace-specific, and scored across channels like META, TIKTOK, DV360, and others.

Key endpoints:

• POST /v1/media — Register a media asset for scoring
• GET /v1/media/{uniqueId}/status — Poll processing status
• GET /v1/scoring/media/{uniqueId}/scores — Retrieve scores
• GET /v1/scoring/workspace/{workspaceId}/scorecards — List workspace scorecards

Creative Aperture API (Creative Tags)

Submit media assets for AI-powered visual annotation. Aperture analyzes the content of each asset and returns structured tags describing what's in it — visual elements, people and emotions, text overlays, brand signals, and more.

Results are returned inline with the status response once the job is complete — no separate fetch step required.

Key endpoints:

• POST /v1/aperture/jobs — Create an annotation job
• GET /v1/aperture/jobs/{job_id}/status — Poll for completion and retrieve results

Account Hierarchy

All API resources are scoped within an Organization. Your API key is issued at the Organization level and grants access to all Workspaces within it.

Organization
└── Workspace (one or more — scoped by brand, region, or team)
    ├── Scorecards (collections of guidelines for scoring)
    ├── Guidelines (individual rules evaluated per asset)
    └── Media Assets (submitted via API or platform)

Most API operations target a specific Workspace. Call GET /v1/organization to enumerate the Workspaces your key has access to and retrieve the workspaceId values you'll need.

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

API keys are scoped by permission level:

• scoring:read — Read scores, scorecards, and media status
• scoring:read_write — All of the above, plus submitting media

Contact your Vidmob account team to obtain an API key or adjust scopes.

Both APIs Are Asynchronous

Neither Scoring nor Aperture returns results immediately. Both follow the same general pattern:

1. Submit — Register a job or media asset, receive an ID
2. Poll — Check status at regular intervals (every 10–15 minutes for Scoring; interval scales with job size for Aperture)
3. Retrieve — Fetch results once status is COMPLETE

Do not poll more frequently than the recommended interval — it will not speed up processing and may trigger rate limiting.

Where to Start

If you're integrating for the first time:

1. Call GET /v1/organization to confirm access and retrieve your workspaceId values
2. Review the scorecards in your workspace: GET /v1/scoring/workspace/{workspaceId}/scorecards
3. Submit a test asset: POST /v1/media
4. Poll status and retrieve scores once complete

The Getting Started guide walks through this flow end to end with example requests.

Support

For questions, integration help, or API key requests: [email protected]