MCP serverco.heista/api

Upload an image to a brand by URL. The pipeline downloads it, runs the vision tagger (classifies type, detects product name, flags is_primary_product), stores it in the brand-asset

Browse proven ad formula blueprints — structural patterns clustered from 3-10+ winning ads that independently converged on the same beat architecture while Meta kept rewarding them

Invoke a Creative Agent (character) preset. Every preset is a purpose-built character the workspace has authored or the Heista catalog has published — copy voice, art direction, st

Heista's creative direction engine — same engine the Creative Director specialist runs internally, exposed over MCP. ONE-SHOT: give a brief, get N finished creative outputs. For ba

Multi-turn conversation with Heista's creative direction engine — a real chat where the agent decides each turn what to produce based on what you ask for. Use whenever the work nee

Check the calling user's Heista API credit balance, month-to-date usage broken down by operation, lifetime spend, and the current pricing for every paid tool. Takes no inputs. Retu

Build a complete creative intelligence profile from internal brand documents — creative briefs, brand guidelines, product specs, customer research, competitive analysis. Takes any

Build the highest-fidelity creative intelligence profile by combining a brand's public website URL with their internal documents. Takes a required website URL plus at least one doc

Build a complete creative intelligence profile of a brand from a single website URL. Takes a website URL (homepage, PDP, landing page) plus optional idempotency_key, force_refresh,

Permanently delete a Creative Library draft that has NEVER been published. Refused for any article with publication history — use creative_unpublish_article to take a live page dow

Read the canonical shelves, taxonomy, relationship Lego, safe content rules, and positional slots for every publishable Creative Library format. Call this before authoring.

Read one Creative Library draft so it can be reviewed before explicit publication.

Read one shelf hub as an object: its public URL, what it covers, what it deliberately does NOT cover (and which shelf owns each of those instead), and every article on it with stat

List Creative Library drafts and publication state. Returns editorial metadata only, not customer data.

Publish only the exact reviewed draft revision. If the draft changed after review, publication fails and the new revision must be reviewed.

Validate and save a complete Creative Library draft using the canonical taxonomy and format-specific content slots. An identical retry is a no-op. It cannot replace published conte

Take a live Creative Library article down. It stops being public and leaves the sitemap immediately. The draft is preserved and can be re-published after review. Use this to revers

Change an article slug and 301 the old URL at the new one. Never leaves two live URLs. Refuses a new slug ending in a year, a slug already in use, and any article whose draft is ah

Decode a specific video ad URL into its full structural formula — beat-by-beat breakdown, hook classification, behavioral psychology stack, creative format, runtime performance sig

Browse individual decoded ads from Heista's corpus of real winning Meta/TikTok creative. Takes optional filters: vertical, creative_format, marketing_angle, hook_type, algo_intent,

Delete one brand asset by asset_id. Removes the brand_assets row and (when the asset was uploaded rather than scanned) the storage object. Destructive — confirm with the user befor

Delete one saved asset by id. Destructive — confirm with the user before calling. OAuth callers can only delete saves they created themselves (Linear model — see /assets UI for org

Dispatch to the DESK RESEARCHER — source-grounded synthesis on a topic landscape. Use for: "what is known about X / give me the landscape of Y / fact-check Z / synthesize the publi

Dispatch to the DESK RESEARCHER — source-grounded synthesis on a topic landscape. Use for: "what is known about X / give me the landscape of Y / fact-check Z / synthesize the publi

Run a full research workflow via the Head of Research agent. The Head decomposes your brief into specialist sub-questions, dispatches the right combination of 6 specialists (desk,

Dispatch to the MARKET ANALYST — entity-deep teardown of a named brand or vendor. Use for: "what is brand X / how does company Y work / decode competitor Z / teardown vendor W". Mu

Dispatch to the MARKET ANALYST — entity-deep teardown of a named brand or vendor. Use for: "what is brand X / how does company Y work / decode competitor Z / teardown vendor W". Mu

Dispatch to the QUALITATIVE RESEARCHER — thematic synthesis from unstructured text (interviews, reviews, forum threads, customer language). Use for: "what are the 2-3 recurring the

Dispatch to the QUALITATIVE RESEARCHER — thematic synthesis from unstructured text (interviews, reviews, forum threads, customer language). Use for: "what are the 2-3 recurring the

Dispatch to the QUANTITATIVE RESEARCHER — numerical analysis with full methodology context. Use for: briefs that turn on numbers done rigorously — "what is the documented effect si

Dispatch to the QUANTITATIVE RESEARCHER — numerical analysis with full methodology context. Use for: briefs that turn on numbers done rigorously — "what is the documented effect si

Dispatch to the SOCIAL LISTENING RESEARCHER — multi-platform community-signal interpretation. Use for: "what are practitioners saying about X across platforms / what jargon is emer

Dispatch to the SOCIAL LISTENING RESEARCHER — multi-platform community-signal interpretation. Use for: "what are practitioners saying about X across platforms / what jargon is emer

Dispatch to the TREND RESEARCHER — recency-dominant trajectory investigation. Use for: "is X a real trend / what is happening with X right now / where is X headed / what is driving

Dispatch to the TREND RESEARCHER — recency-dominant trajectory investigation. Use for: "is X a real trend / what is happening with X right now / where is X headed / what is driving

Toggle the favorite flag on a saved asset. Pass is_favorite=true to favorite, false to unfavorite. favorited_at is set/cleared in lockstep so the Favorites tab sorts correctly. Not

Drill into a specific URL after search surfaces it. Returns the extracted text content plus metadata. Internal routing: PDFs hit Anthropic Files API for OCR + structured extraction

Aggregate marketing analytics for the last 7/28/90 days: pageviews, visitors, sessions, AI-search-referred sessions, the view→engaged→CTA→signup→trial funnel, and top pages. Aggreg

Top marketing pages by views for the last 7/28/90 days, optionally filtered to a path prefix (e.g. "/decode", "/intelligence", "/brands"). Includes engagement signals where capture

Daily pageview series for the last 7/28/90 days, split by traffic source category (ai_search / organic / social / direct / referral). Use to measure launch weeks and content moment

Server-logged crawler fetches: which AI engines (GPTBot, ClaudeBot, PerplexityBot, OAI-SearchBot, …) and search crawlers (Googlebot, Bingbot) fetched which heista.co pages, and whe

File an issue on the Heista HEI board: title, markdown description, optional labels (Bug, Feature, Improvement, Security, SEO, Tech Debt, Upstream, In-App Support, In-App Feedback)

Read one live brand report in full by slug, including the creative intelligence payload used on the public brand page — proof points for outreach and positioning. Read-only.

Read one published decode in full by id or slug, including its public structural payload (beats, classification, patterns — the same data rendered on the public decode page). Use f

Read one Heista Linear issue in full by identifier (e.g. "HEI-14") or UUID: title, state, priority, assignee, labels, full description, and recent comments (including the automated

Google URL Inspection for one heista.co URL: index verdict, coverage state ("Submitted and indexed" / "Crawled - currently not indexed" / "URL is unknown to Google"), last crawl ti

LIVE Google Search Analytics query — group by any dimensions (date, page, query, country, device, searchAppearance; up to 3) with page/query filters over up to 16 months of history

Sitemaps registered on the Search Console property with submitted vs indexed counts, last-download time, warnings and errors. The indexing-progress scoreboard — as of Jul 2026 the

Google Search performance totals from first-party Search Console data (synced 6-hourly): clicks, impressions, CTR, impression-weighted average position, distinct queries and pages.

Top pages by Google search clicks or impressions from first-party Search Console data, optionally filtered to queries containing a term. Use to find which pSEO pages earn search de

Top Google search queries by clicks or impressions from first-party Search Console data, optionally filtered to pages containing a path (e.g. "/decode"). The core tool for briefing

Canonical Ad Intelligence corpus counts — the single source of truth that kills number drift across marketing surfaces. Returns decoded ads published (THE number to quote publicly)

List live brand-level Ad Intelligence reports (the public /decode/brand pages). Optional brand-name filter, paginated, hard cap 50 rows. Returns identifiers + ad counts + public UR

List live intelligence articles — the weekly and per-vertical category report system behind the public intelligence surfaces. Filter by kind (weekly/category) or vertical. Note: in

List issues on the Heista Linear board (team HEI) — the read-only window into what the dev agents are working on, what's broken, and what's shipped. Filter by workflow state ("Back

The signup -> trial -> paid funnel as COUNTS ONLY, with no customer PII scope required: signups, trials active, trials expired unconverted, converted to paid, onboarding completed,

Aggregate conversion/drop-off stats for a signup cohort (last N days, max 90): trial active vs expired-unconverted vs converted-to-paid, conversion rate, never-spent-a-credit rate,

List recent signups (last N days, hard cap 50 rows) with the same product-backend shape as fleet_product_user_summary — trial/credits/plan/onboarding/Heists per user. Use to see th

Look up ONE customer's product-backend state by email: trial status, credit balance, workspace plan, installed Heists, onboarding completion, plus PostHog attribution/engagement si

Search the published Ad Intelligence corpus (the public decode gallery). Filter by free-text (name/tagline/brand), brand, category, vertical, or platform. Returns list rows with pu

One-row verification scorecard for the indexing-recovery plan (internal-linking-spec-v2): site-wide + /decode-specific orphan counts (200 but zero internal inlinks) from the latest

One-row health scoreboard from the weekly full-site crawl: total pages, OK/redirect/error counts, ORPHAN pages (200 but zero internal inlinks — the primary indexing-recovery target

Internal links for one page: direction "in" = who links TO it (zero inlinks = orphan), "out" = what it links to. Link data comes from the first render of sitemap-listed pages (pagi

Filterable inventory of every sitemap-listed page with SEO facts (title, meta description, canonical, h1, word count, JSON-LD) and internal inlink/outlink counts from the weekly cr

Generate direct-response video ad scripts by fusing a proven structural source (decoded ad or formula) with a brand's PowerSource. Output is feed-native ad copy for paid social (Me

Get one ad formulas preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get a brand's full canonical record — name, domain, voice (tone_of_voice), story, visual identity (logo, primary color, visual assets), and counts. Use to inspect what a brand carr

Get one saved cards preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get one creative agents preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get one creative agent skills preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get one creative director playbooks preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-onl

Retrieve the full decode bundle for a previously-submitted ad, or poll the status of a running decode job. Takes a single job_id (UUID returned by decode_ad). Returns either status

Get one decoded ads preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get the current status of a specialist dispatch job started via dispatch_<specialist>_async. Returns { status: queued|running|completed|failed, result_text?, error_text?, error_cla

Read-only walk of a fleet session tree. Given any session_id in the tree (root, Head, Mastermind, or specialist sub-node) returns the full breakdown: every session row with depth +

Browse proven hook patterns from Heista's corpus of decoded winning Meta/TikTok ads. Takes optional filters: vertical (e.g. BEAUTY_SKINCARE, SUPPLEMENTS, APPAREL), hook_type (e.g.

Get one static ads preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get one outfits preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Retrieve the full creative intelligence profile for a previously-submitted PowerSource scan, or poll the status of a running scan. Takes a job_id (UUID returned by any create_power

Fetch one saved asset by id. Returns the full row including category, format, tags, body_text/html, signed media_url (if private storage), metadata, creator, brand, and timestamps.

Fetch up to 50 saved assets by id in one round-trip. Use when an agent needs to pull a pre-selected set — e.g. resolving a saved_asset_picker context input on a Heist that requires

Get one saved visual ideas preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Read a creative strategy in full by its powersource_id. Returns the same brand-merged bundle shape as get_powersource(data) — buyer profile, 12 behavioral tensions, angles, narrati

Get one models preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get one visuals preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get one visual styles preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Cluster-level structural formulas derived from decoded ads. Heista-curated; served as a generation parameter. Read-only, free. Filter scope with only_workspace / only_official (mut

List images for a brand. Filter by PowerSource (this scan only, via powersource_id), by on-pack product_name (the vision tagger's read), by type (logo, product, product_cutout, her

List indexed brand documents for a brand. Each row carries the indexed signals (doc_type, summary, key_topics, classification_confidence, indexing_status) plus mime_type and size_b

List every brand in this workspace. Use this BEFORE creating a PowerSource to avoid creating duplicate brand records (pass the matching brand_id to create_powersource_*), and to di

Cards the user bookmarked from Creative Director chat — directions, concepts, executions, brand platforms, art directions, visual sets. Surfaces in /library + the chat-side tray. S

Reusable creative agents the Heist can pick as a handoff target — picked from the UI, callable as an MCP tool from Managed Agents. Workspace = private agents in the org. Official =

Portable craft skills (frameworks + method + worked examples) a Creative Agent loads ON TOP of its worldview — additive and stackable, never substitutive (unlike a creative_directo

Seven-section creative-mechanism lenses the Creative Director chat picks at session start. The picked playbook substitutes Layers 3 + 4 of the system prompt — voice + foundation —

Structural references for script-led Heists. Workspace decodes (your video_sources scans joined with their video_scan_frameworks) + Heista-curated decoded ads from official_ad_heis

Static-ad references for image-led Heists. Workspace static scans + Heista-curated image ad heists. Read-only, free. Filter scope with only_workspace / only_official (mutually excl

Styled outfits — a talent dressed in a full look, saved as one composite sheet (turnaround + wardrobe detail crops) with structured refs to the product images that built it. The Ou

List all projects (campaign folders) for a brand. A project groups strategies, documents, client assets, and outputs under one campaign. Returns project_id (pass as project_id to l

List saved assets in the workspace. Filter by category (STRATEGY, IDEAS, COPY, VISUALS, MOTION, BRIEFS), by one or more formats inside the category (e.g. COPY + formats=["ad-script

Visual ideas you saved from prior generations. Workspace-only. Read-only, free. Filter scope with only_workspace / only_official (mutually exclusive — same toggle as the in-app lib

List skills available in the Heista skill library. Returns name, description, domain (shared / image / video / research / strategy / copy / creative / generation), type (foundation

List all PowerSource strategies (scans) for a brand. A brand has many strategies — one per scanned URL. Product-page strategies carry product_name and is_product_page=true; use the

List audience archetypes for a strategy (PowerSource). Returns the Buyer Decoder archetype (source="buyer_profile", one entry max) plus up to 3 offering primary_audience segments (

List tone profiles for a strategy. Today returns at most one entry — the tone_of_voice synthesized by the Tone of Voice Synthesis agent (POWER-mode bundles only). The shape is list

Saved casting talent — a person you can re-use across Heists. The Models Heist saves them on click; future Heists can pick one as a brand-aware talent reference. Workspace = your s

Visual presets (style reference sets) backed by visual_heists. Dual scope since 2026-07-14: workspace rows saved from the Visual Preset builder + the Heista-curated official catalo

Saved style configs picked into image-led Heists. Workspace = org-owned styles. Official = canonical Heista catalog (org_id IS NULL, is_canonical=true). Read-only, free. Filter sco

Load the full SKILL.md body for one skill by canonical dot-notation name (e.g. "research.foundation", "research.methodologies.desk-synthesis", "shared.registers.cinema-mode"). Retu

Load one reference file from a register-type skill's references/ folder (e.g. "m1-narrative.md" from "shared.registers.cinema-mode"). Only register-type skills have references/ — f

Web-grounded search via Perplexity Sonar Pro. Returns synthesized answer text plus a structured sources[] array (url + title) the caller can evaluate per the research.foundation fo

Read one indexed brand document. Returns the indexed metadata (doc_type, summary, key_topics, entities, key_quotes) plus the document body as plain text in content.text — every mim

Batch re-run the vision tagger against every asset in a brand that hasn't been reviewed yet (vision_classified=false). Recovers rows the scan-time tagger dropped because of CDN blo

Re-run the vision tagger on one brand asset. Reads the stored object when present (uploaded assets) or the original URL (scan-sourced assets), then updates type, detected_product_n

Persist a new saved asset to the workspace. category MUST be one of STRATEGY, IDEAS, COPY, VISUALS, MOTION (BRIEFS lives in creator_briefs and is not saveable through this tool). f

General-purpose web grounding via parallel.ai (Vercel AI Gateway). Returns synthesized text excerpts plus structured sources[] with direct URLs. Use for: topic landscapes, entity-

Community-discourse search via parallel.ai with optional platform filtering. Returns synthesized text excerpts plus direct URLs to real Reddit threads, X posts from named operators

Structured fact-check + numerical research via Perplexity Sonar Reasoning Pro (Gateway-routed). Returns synthesized answer text plus structured sources[] with direct URLs to primar

Find skills across EVERY Heista skill library at once — image craft, fleet foundations and model briefings, Heista DNA creative playbooks, creative agents, and agent skills. Descri