# Creative Tagger

> The taxonomy standard for performance marketing. At launch, Creative Tagger accepts uploaded video, image, and carousel creative plus supplied email HTML, and returns a stable taxonomy with brand-custom attributes, recognized entities, performance memory, and standardized naming. Landing-page and other remote URL fields remain compatibility-only while outbound fetching is security-hardened. Creative Tagger runs as an API and as a hosted MCP server for Codex and compatible bearer-token Streamable HTTP clients.

## Connect an agent (MCP)

Creative Tagger runs a hosted remote MCP server (Streamable HTTP) at `https://api.creativetagger.ai/mcp/`. Codex CLI, the IDE extension, and the ChatGPT desktop app's Codex host can connect through shared MCP settings or `~/.codex/config.toml` with `bearer_token_env_var = "CREATIVE_TAGGER_API_KEY"`. ChatGPT web apps and Claude hosted connectors require standards-based OAuth; Creative Tagger has not enabled that flow yet, so do not paste an API key into those connector screens. The published `creative-tagger-mcp==0.2.4` package is the current local stdio surface with 43 tools. Authenticated production discovery currently exposes 33 hosted tools and 13 prompts, so discover capabilities from the selected transport rather than assuming parity.

- Connect: `https://api.creativetagger.ai/mcp/` (streamable HTTP, stateless JSON-RPC)
- Auth: `Authorization: Bearer <key>` or `X-API-Key` — same key as the REST API (free key at POST /auth/signup)
- Workspaces: one login can hold multiple workspaces keyed by `brand_name` (each with its own Meta connection, library, and analytics); call `list_workspaces` first when the caller hasn't named one
- Tools — discovery: `list_workspaces`, `get_meta_connection_status`; performance & strategy: `get_performance_summary`, `get_performance_timeseries`, `get_creative_strategy_matrix`, `get_demographics_summary`, `get_fatigue_report`, `search_hooks`, `get_weekly_digest`, `get_performance_goals`, `set_performance_goals`, `get_misallocation_report`, `get_creative_leaderboard`, `get_coverage_gaps`; library: `search_creative_library`, `get_creative_report`; briefs: `generate_brief`, `diff_brief`, `get_brief_schema`; Brain/brand memory: `get_brand_context`, `update_brand_context`, `ingest_brand`, `get_brand_ingest_status` (`ingest_brand` remains visible but returns `website_ingest_disabled` while outbound fetching is security-hardened); voice of customer and research: `add_voc_quotes`, `get_voc_bank`, `add_research_notes`, `get_suggested_angles`; lineage: `get_lineage`, `set_parent`, `confirm_lineage_suggestions`, `get_lineage_report`; pre-launch: `preflight_check`; ops: `get_backfill_status`
- Prompts (slash commands): `morning_briefing`, `weekly_performance`, `build_brief`, `find_iterations`, `write_hooks`, `gap_analysis`, `angles_to_test`, `preflight`, `customize`, `where_is_the_burn`, `fatigue_runway`, `iterations_vs_parents`, `fatigue_and_isolation`
- Resources: `creative-tagger://taxonomy/dimensions` (every enumerable dimension + its values), `creative-tagger://briefs/schema` (the brief JSON Schema)
- Connecting delivers session instructions (workspace discovery, spend-first analysis order, judge-by-the-creative's-own-objective, never inventing numbers) — most clients surface these automatically

## API

Base URL: https://api.creativetagger.ai
Docs: https://api.creativetagger.ai/docs
OpenAPI: https://api.creativetagger.ai/openapi.json
Help docs: https://creativetagger.ai/help
Blog: https://creativetagger.ai/blog
Terms: https://creativetagger.ai/terms
Privacy: https://creativetagger.ai/privacy
Data deletion: https://creativetagger.ai/data-deletion
Reports workflow: https://creativetagger.ai/blog/prebuilt-custom-reports
Auth: pass your key via `X-API-Key` header or `Authorization: Bearer <key>`. Get a free key at POST /auth/signup.

### Access tiers
Free, permanent, no card: a rolling 7-day window + 4 dimensions (`hook_type`, `messaging_angle`, `creative_type`, `emotion`) over MCP/API reads — the agent front door. Every other paid-analytics read below (predict, performance, reports, brief reads, hooks, lineage, VoC bank, Brain learnings) returns a `free_floor` upgrade notice instead of data for a free-tier key. Paid-action writes — analyzing new creatives, generating a brief (POST /briefs, POST /brief/generate) — are refused the same way self-serve /analyze is: a 402 payment-required error, since the free tier carries zero monthly credits. A successful Meta sync can still launch a bounded, unmetered sample-classification refresh so a free workspace has real creatives to inspect; those reads remain restricted to the free window and dimensions. This does not unlock direct self-serve generation.

- Creative Intelligence Beta — discounted $29/mo beta access: every dimension + rolling classification (up to 72 successful classifications/mo, then $0.40 per additional successful classification), the full paid-analytics surface, and one completed historical Meta import per subscriber across all workspaces and Meta accounts, up to 37 months
- Archived Pay-as-you-go, Starter, Growth, Scale, and Enterprise identifiers are retained only for webhook/history reconciliation. They grant no runtime paid entitlement, create no local $0.40 debt, and are not `checkout_products` offers.
- Meta history import is included with an active Creative Intelligence subscription; there is no separate new-customer backfill checkout
- GET /billing/plans — plan metadata plus `checkout_ready`, `checkout_products`, secret-safe `missing_config`, and per-plan `checkout_enabled`; treat this response as the source of truth for currently available checkout capability
- POST /billing/checkout — returns a Polar checkout URL only for an offered product after runtime and product-specific configuration are ready; otherwise it returns an honest configuration-unavailable response
- Included history import: GET /meta/backfill/quote → POST /meta/backfill/start → GET /meta/backfill/jobs/{job_id}; an inactive subscriber must first use POST /billing/checkout for the `intelligence` plan. The legacy POST /billing/checkout/backfill route never creates a new standalone purchase.

### POST /analyze
Classify the currently shipped launch inputs. Multipart form data:
- `file` — image/video upload · `files` — multiple files (carousel)
- `html_content` — raw email HTML rendered with external network requests blocked
- `file_url`, `video_url`, and `page_url` remain compatibility fields but temporarily return `customer_url_fetch_disabled` while outbound requests are security-hardened; upload the creative instead
- `brand_name` (required) · `format` (optional) — force video, image, carousel, landing_page, email, or long_video

Returns the standard taxonomy (always present, for cross-brand reporting) plus:
- `brand_attributes` — brand-custom values (founder, customer segment, product, offer, ICP, campaign label)
- `recognized_entities` — matched founders, creators, customers, spokespeople, products, offers, segments, campaigns
- `trending_audio` — optional for video/long-video responses: matched audio metadata when fingerprinting and lookup complete; `unavailable_reason` explicitly distinguishes disabled or missing dependencies, no audio, and lookup outages from a verified non-match
- four naming conventions: standard, full, compact, reporting

Batch: POST /analyze/batch and POST /analyze/batch/stream (NDJSON progress).

### POST /predict — observational pre-flight evidence
Compare a not-yet-run creative's tags with the brand's own historical account performance. The endpoint name remains `/predict` for compatibility, but the response is not an outcome prediction and makes no causal claim. It returns:
- `schema_version: "predict_observational.v2"`, `evidence_type: "observational_association"`, `causal_claim: false`, and `outcome_prediction: false`
- `association_score` (0–100): the average brand-relative historical percentile across matched tags on one declared objective metric; this is descriptive, not a probability or forecast
- per-dimension observed metric values, spend, row counts, association percentiles, and explicit limitations
- `test_hypotheses`: alternate tag values nominated from historical associations, each with observed comparator evidence and an eight-field controlled-test preregistration plan; no estimated lift or causal "swap" is returned

Every request must send `contract_version=predict_observational.v2`; absent or different versions fail closed with a non-2xx contract-mismatch response. The endpoint uses the workspace's one eligible objective metric when available. For mixed, blank, or unknown objectives, pass a supported `objective_metric` (and optionally its matching `goal_direction`); ROAS is never assumed. The minimum evidence floor counts distinct creative assets rather than dated performance rows, and metrics without their denominator or funnel stages are unavailable rather than zero-ranked. Historical performance may be confounded by audience, placement, budget, timing, offer, and delivery optimization. Predeclare the experimental control, evidence threshold, decision trigger, and staged budget before testing or scaling. Requires imported performance history for the brand (see Performance memory).

### Strategist
- POST /strategist/recommend — prioritized creative recommendations from your library and performance
- POST /strategist/gaps — untried taxonomy combinations (coverage gaps) worth testing
- POST /chat — multi-turn strategist conversation grounded in brand memory, custom taxonomy, library patterns, and account performance; pass `analysis_id` to focus on one creative
- POST /preflight — pre-flight a batch of NOT-YET-LAUNCHED creative uploads: classifies each, then scores conceptual diversity (near-duplicate pairs get ~zero incremental Meta delivery; 8–15 distinct variations is the floor), overlap with your live creative mix, and which matrix gaps the batch covers. `file_urls` temporarily returns `customer_url_fetch_disabled`; drafts are not saved to the library.
- POST /brief/generate — legacy bulk brief generator: pass an array of past `/analyze` results + notes, get strategic insights and 3 draft briefs that fill library gaps. See Briefs below for the current brief flow.

### Briefs
- POST /briefs — generate and store a schema-v2 creative brief: falsifiable hypothesis, 3-5 verbatim hooks, timed storyboard beats, Brain-sourced guardrails, deliverables matrix, success metrics, and naming strings. `brief_type` is `net_new` or `iteration` (iteration requires `parent_analysis_id` + `iteration_type`)
- GET /briefs/{brief_id} — fetch a stored brief plus its outcomes
- GET /briefs/{brief_id}/diff/{analysis_id} — brief-vs-delivered deviation report: matches, deviations, guardrail violations, storyboard beats present vs missing
- GET /briefs/{brief_id}/render — shareable 1-2 page HTML rendering

`iteration_type` vocabulary (shared with lineage below): hook_swap, body_swap, format_shift, emotional_recut, creator_swap, offer_swap, new_concept.

### Performance memory (Meta) — native read-only OAuth
Read-only. Connect Meta through Creative Tagger OAuth; Creative Tagger never writes to your ad account.
- POST /auth/meta/connect/start — start read-only Meta OAuth for `ads_read`
- GET /auth/meta/status — check whether Meta is connected
- GET /auth/meta/adaccounts · POST /auth/meta/adaccount — list and select the ad account to sync
- DELETE /auth/meta/connection — disconnect (optional `purge_data=true` also deletes synced data)
- POST /meta/sync — sync ad-level performance and age × gender demographics into brand memory (also kicks off a free sample-classify pass on first sync)
- POST /meta/sync/start · GET /meta/sync/status/{job_id} — the same sync as a background job, for larger accounts
- GET /meta/sample-classify/status/{job_id} — progress of the free onboarding classification pass
- GET /meta/media-retry/status/{job_id} — status of the bounded degraded-media re-fetch retry a sync can kick off
- GET /meta/performance/summary — winners and losers by standard and brand taxonomy, with brand-relative ratings
- GET /performance/by-taxonomy — tag-level spend, ROAS, CTR, and thumbstop per dimension, plus untried coverage gaps
- GET /performance/demographics — observational age × gender delivery and account-relative return-per-spend bands; withholds audience outcome and action recommendations until a metric and direction are predeclared
- GET /performance/timeseries — dated performance points per creative/campaign with a fatigue signal
- GET/PUT /auth/performance-targets — set per-workspace CPA/ROAS targets that override the account-average default the analytics engine grades winner/loser against

The dashboard's explicit Sync action, the automatic initial refresh after account selection, and scheduled refreshes all use the same durable performance → demographics → bounded sample-classification → degraded-media retry pipeline. Connected workspaces become due every 8 hours by default; each scheduler scan is bounded and skips a workspace that already has an active sync job. `/auth/meta/status` reports the active job plus an opaque `data_version`, data-through/effective-window dates, last attempt and snapshot times, next scheduled time, completeness, and a server-owned health state (`fresh`, `updating`, `partial`, `stale`, `failed`, or `status_unavailable`). Open dashboard tabs revalidate that lightweight status periodically and on focus, invalidate report caches when the version changes, and withhold decision claims when freshness cannot be proved. Meta-synced media prefers full-resolution images and playable video URLs, and reports unavailable video honestly when Meta exposes only a thumbnail. Product labels are resolved from Brand Brain entities, destination evidence, and creative evidence; unresolved creatives stay unresolved rather than receiving an invented product.

Native Meta OAuth is required for the launch customer flow.

Ratings are relative to each brand's own distribution per metric (percentile, label, and a 0–1 goodness score, cost-inverted for CPA). Attribution/lookback windows are configurable (default 7d-click, 1d-view).

### Reports
- GET /reports/prebuilt — Motion-style prebuilt reports: best hooks, landing pages, angles, audiences, offers, CTAs, visual formats, and brand-custom values; brand-relative and significance-gated
- GET /reports/creative-strategy — the creative strategy matrix: taxonomy rows × columns (default angles × formats) with per-cell winner/loser/fatigued/untested status and a decision queue of what to test next
- GET /reports/decision-queue · POST /reports/decision-queue/triage — the paged, persisted triage inbox behind that decision queue (accept/dismiss/reopen a matrix cell)
- POST /reports/custom · GET/POST /reports/custom/saved · GET /reports/custom/saved/{report_id}/run · DELETE /reports/custom/saved/{report_id} — build and save a custom report over any taxonomy dimensions + metric
- GET /reports/creatives — one card per creative for the report wall: media, classification, all performance metrics, fatigue tier, lineage position, and the latest review decision
- GET /creatives/{analysis_id}/report — full per-creative detail: weekly timeseries, video funnel, full classification, expanded lineage family, any linked brief + brief-diff, and the review thread
- GET/POST /creatives/{analysis_id}/reviews — the review thread: append-only notes plus a team decision (`keep`, `iterate`, `kill`)
- GET /reports/weekly-digest — the week's winners-channel artifact: winners/losers, concept families, new fatigue entries, matrix mix shifts, and naming strings (`format=markdown` for Slack)
- GET /reports/creatives/leaderboard · GET /reports/creatives/batch · GET /reports/compare — evidence-gated creative ranking, launch-cohort readouts, and non-overlapping period comparisons
- GET /reports/misallocation · GET /reports/trends — spend-vs-result misallocation and weekly objective-aware trend diagnostics. These API routes are deployed; their dedicated dashboard launch surfaces remain feature-gated.

### Brand taxonomy — auto-generated
- POST /brand-taxonomy/generate — cluster a brand's analyzed library into messaging themes, intended audiences, and typed entities (product, founder, creator, offer, customer_segment, campaign_label), each self-defined. No manual setup required.
- GET/POST /auth/brand-taxonomy; GET/POST/DELETE /auth/brand-taxonomy/values and /auth/brand-taxonomy/entities
- POST /auth/brand-taxonomy/reapply — re-apply the current taxonomy over every already-saved analysis at zero AI cost, so a newly added value or entity populates matrix history instantly
- GET/POST/DELETE /auth/brand-context and GET /auth/brand-contexts — brand voice, audience, and memory
- POST /auth/brand-context/ingest-website — temporarily returns `website_ingest_disabled` while the user-controlled crawler is security-hardened. Existing Brain data remains readable/editable; GET /auth/brand-context/ingest-website/{job_id} remains available for prior job history.

### Library and memory
- GET/PATCH /auth/library · GET /auth/library/patterns · GET/PATCH/DELETE /auth/library/{analysis_id}
- GET /auth/library/{analysis_id}/media · POST /auth/library/{analysis_id}/share · GET /auth/shared/{token}

### Hooks, lineage, and customer language
- GET /hooks — the hook library: verbatim first-3-second lines and text overlays per creative, joined with spend, hook rate, and delivery longevity (`format=csv` exports)
- GET /lineage · POST /lineage/parent · POST /lineage/confirm — iteration lineage: concept families (parent/child versions) with per-version performance, plus auto-suggested parents from version-token names and near-duplicate dimension mixes; confirm pending suggestions only by the exact reviewed analysis/parent pairs
- GET /voc/bank · POST /voc/quotes — read and bank verbatim customer language (reviews, ad comments, support quotes), auto-tagged with one of six VoC angle types (problem_aware, solution_aware, social_proof, curiosity, benefit_driven, authority)

### Naming
- POST /auth/naming/preview · GET/POST/DELETE /auth/naming/templates · GET /auth/naming/variables

### Brain learnings
- GET /brain/learnings — auto-written performance learnings from account history: winners, watch-list signals, fatigue, and audience notes
- POST /brain/learnings/save — persist the current auto-written learnings into saved Brain notes

### Competitors
Read saved competitor Meta Ad Library scans and compare their strategy to yours. Native scanning is provider-gated; check launch health and do not promise a live scan while `competitor_analysis` is false.
- POST /competitors/scan — when the provider feature is enabled, scan a competitor's ads (by `page_id`, `page_name`, or `keyword`) and analyze their creatives; returns an aggregate strategy breakdown (hook types, visual styles, CTAs, emotions, spend)
- GET /competitors/history · GET /competitors/history/{scan_id} — saved scan history

### Account
- POST /auth/signup · POST /auth/login — password login remains available for the invite-only beta
- POST /auth/login/magic-link — passwordless email recovery is enabled. A successful request returns generic `202` acceptance whether or not an active account exists; acceptance does not confirm account existence or delivery. When delivery succeeds for an eligible active account, the one-time sign-in link is valid for 15 minutes. `429` means too many requests; uniform `503` means email sign-in is temporarily unavailable. Retry later or use password sign-in/support.
- POST /auth/login/magic-link/verify — exchange an unused, unexpired link token for a login session. Invalid, expired, already-used, or inactive-account tokens return `401`.
- Production email links should issue the credential as `#login_token=…`; legacy `?login_token=…` links remain accepted for transition compatibility. A page can scrub a query token before subresources load, but it cannot remove that credential from the initial navigation request or browser/network history after the fact. Fragment issuance avoids sending the token to the site in that initial request, but the credential can still remain in the browser's navigation-timing entry for that document; same-document scrubbing is not retroactive erasure.
- GET /auth/me · GET /auth/keys · POST /auth/keys/rotate · GET /auth/usage · GET /auth/credits
- POST /auth/workspace/rename · GET/PUT /auth/workspace/auto-analyze-overage — rename a workspace, or toggle paid auto-classification past its monthly credit cap
- GET /auth/webhooks · DELETE /auth/webhooks/{webhook_id} — inspect or remove existing destinations. POST registration and customer webhook delivery are temporarily disabled while DNS-rebinding-safe outbound delivery is built; existing rows are inert.

## Standard taxonomy (always present) — v2

Taxonomy v2 separates media type, production class, and execution style into
three clean dimensions instead of mixing them: Media Type (Static, Video,
Carousel — the auto-detected format, always known, not AI) is distinct from
Asset Type (production class) and Visual Format (execution style). A creative's
Media Type is reported at the top level (`format`); Asset Type and Visual
Format are classification attributes below.

### Visual
- Asset Type: UGC, Lifestyle, Product Shot, Studio, High Production, Screen Recording, Stock, AI Generated, Animation, Mixed Media
- Visual Format: Talking Head, Testimonial, Before After, Unboxing, Problem Agitate, Listicle, Text Overlay, Mashup, Demo, Social Proof, Founder Story, Comparison, Tutorial, Meme, Scroll Stopper, Skit, Podcast Clip, Green Screen, Slideshow
- Visual Style: Minimal, Bold, Organic, Dark, Bright, Editorial, Lo-Fi, Hi-Fi, Native Feel, Branded, Retro, Clean

### Talent
- Talent Type: No Talent, Creator, Model, Founder, Customer, Voiceover Only, Hands Only, Employee, Expert, Influencer
- Talent Age Group: child, teen, age_18_24, age_25_34, age_35_44, age_45_54, age_55_plus, mixed, none
- Talent Gender: female, male, mixed, ambiguous, none

Age Group and Gender are apparent visual estimates for on-screen talent, not verified demographic data.

### Persona
- Audience: dynamic (AI-generated per brand)
- Messaging Angle: dynamic (AI-generated per brand)

### Hook
- Hook Type: Question, Bold Claim, Callout, Contrarian, Confession, If Then, Statistic, Urgency, Curiosity Gap, Social Proof, Pain Point, Transformation, Challenge, Story Open, Pattern Interrupt

### CTA
- Shop Now, Learn More, Sign Up, Get Offer, Book Now, Download, Subscribe, Watch More, Swipe Up, Try Free, No CTA

### Audio
- Audio Type: Voiceover + Music, Voiceover Only, Music Only, Trending Sound, Native Audio, Silent
- Voiceover Tone: Conversational, Urgent, Authoritative, Friendly, Whispery, Energetic, Calm, None

### Emotion
- Urgency, Curiosity, Trust, Fear, Desire, Humor, Aspiration, Relief, Belonging, Neutral

### Metadata
- Seasonality: Evergreen, Black Friday, Cyber Monday, Holiday, New Year, Valentines, Mothers Day, Fathers Day, Back To School, Summer, Spring, Fall, Prime Day, Launch, Flash Sale
- Offer Type: No Offer, Percent Off, Dollar Off, Free Shipping, BOGO, Bundle, Free Gift, Subscribe Save, Limited Time, Clearance
- Aspect Ratio: 1x1, 4x5, 9x16, 16x9, 1.91x1
- Duration: 6s, 15s, 30s, 60s, 90s+

## Naming templates
- Standard: Brand_AssetType_Format_Talent_Hook_CTA_Ratio_V1
- Full: all dimensions
- Compact: Brand_Format_Talent_CTA_Ratio_V1
- Reporting: Brand_AssetType_Format_Audience_Angle_Hook_Season_V1

Brand naming templates can also use brand-specific variables such as founder, creator, customer, spokesperson, product, offer, customer_segment, icp, and campaign_label.

## Integration
- MCP server: hosted at `https://api.creativetagger.ai/mcp/` for Codex and compatible bearer-token clients (33 hosted tools and 13 prompts by authenticated production discovery); `creative-tagger-mcp==0.2.4` is the current published local package for stdio clients (43 stdio tools)
- Python SDK: `pip install creative-tagger`
- OpenAPI spec: https://api.creativetagger.ai/openapi.json

## Use cases
- Tag and classify uploaded video, image, and carousel creative or supplied email HTML at scale against a stable, cross-brand taxonomy
- Compare a creative's tags with objective-aware historical account associations before spend, without forecasting its outcome
- See which tags, audiences, and offers correlate with observed performance and turn promising gaps into controlled tests
- Auto-build a per-brand taxonomy from your own analyzed library
- Generate standardized naming conventions for ad platforms
- Ground new hooks and briefs in your own banked customer language instead of guessing
- Track iteration lineage (v2/v3 concept families) and what actually moved the numbers
- Read saved competitor scans, and run live Meta Ad Library scans when the provider feature is enabled
- Plug creative intelligence into Codex or a compatible bearer-token MCP client