Agents-first viral-hook engine: generate, score, and remix short-form hooks over MCP.
Inferred from the transports this listing declares (streamable-http). A client not listed here hasn’t been ruled out — it just isn’t something Forge can confirm.
Verification confirms publisher identity (repo ownership), not code safety. The security scan covers known CVEs and suspicious install scripts.
Read from a real MCP initialize → tools/list handshake against the declared endpoint. No tool was ever invoked — tools/list is the read-only introspection call the protocol defines for this. It reflects what the server advertised at that moment; a hosted endpoint is not pinned to any version and can change without notice.
https://engine-production-3bdc.up.railway.app/mcp45 tools · 380mssignupRedeem a private-beta code and create an account. No API key needed.
Standard codes are single-use with ten product requests. Owner codes are reusable
and unlimited. Signup retains 500 credits as a compatibility balance, while
customer pricing is zero during beta. An exact idempotent replay ret…Redeem a private-beta code and create an account. No API key needed. Standard codes are single-use with ten product requests. Owner codes are reusable and unlimited. Signup retains 500 credits as a compatibility balance, while customer pricing is zero during beta. An exact idempotent replay ret…
| Parameter | Type | Description |
|---|---|---|
| beta_access_code* | string | Private-beta invite code: exactly eight ASCII digits. |
| idempotency_key* | string | Required replay key for beta signup. Reuse it only for exact retries. |
| name | string | Display name for the account, 1-100 chars. Purely a label (it is never checked for uniqueness); defaults to 'agent'. |
| — | OPTIONAL contact address. Never required, never verified, and never used to authenticate; the api_key is the only credential. |
getting_startedThe 5-step agent quickstart: modes, wait guidance, links. Free, no auth.
Written to be parsed and acted on. Returns {what_this_is, five_steps, modes
(cost + live latency + when to use), wait_guidance (expected_wait, estimates,
progressToken, jobs), links}.The 5-step agent quickstart: modes, wait guidance, links. Free, no auth. Written to be parsed and acted on. Returns {what_this_is, five_steps, modes (cost + live latency + when to use), wait_guidance (expected_wait, estimates, progressToken, jobs), links}.
No input schema was published for this tool.
list_archetypesList the hook archetypes with psychology, platforms, and templates. Free, no auth.
Returns {archetypes:[{id, name, description, psychological_trigger, best_for,
templates}]}. Use an id for generate_hooks(archetypes=[...]) or
remix_hook(target_archetype=...).List the hook archetypes with psychology, platforms, and templates. Free, no auth. Returns {archetypes:[{id, name, description, psychological_trigger, best_for, templates}]}. Use an id for generate_hooks(archetypes=[...]) or remix_hook(target_archetype=...).
No input schema was published for this tool.
pricingThe machine-readable price list, with per-mode expected_wait. Free, no auth.
Every customer operation is zero-priced during private beta. Returns {unit,
usd_per_credit:0, beta, operations, pricing_modes with zero base/per_hook,
expected_wait}. Internal provider-credit ceilings are separate from…The machine-readable price list, with per-mode expected_wait. Free, no auth. Every customer operation is zero-priced during private beta. Returns {unit, usd_per_credit:0, beta, operations, pricing_modes with zero base/per_hook, expected_wait}. Internal provider-credit ceilings are separate from…
No input schema was published for this tool.
get_estimatesThe measured/expected wait per generation mode. Free, no auth.
Size a call before spending. Returns {op, modes:{instant|smart|research:
{p50_ms, p90_ms, samples, source ("measured" once enough samples, else
"default"), advice}}}.The measured/expected wait per generation mode. Free, no auth. Size a call before spending. Returns {op, modes:{instant|smart|research: {p50_ms, p90_ms, samples, source ("measured" once enough samples, else "default"), advice}}}.
No input schema was published for this tool.
healthDeep health: DB read+write probe, worker/queue, backup + integrity. Free.
Uses the same DB, backup, offsite, and integrity probes as GET /health; status is
"ok" only when the DB reads and writes. Returns status/time/LLM, outcome, queue,
backups, integrity, running synthesis and delivery postures…Deep health: DB read+write probe, worker/queue, backup + integrity. Free. Uses the same DB, backup, offsite, and integrity probes as GET /health; status is "ok" only when the DB reads and writes. Returns status/time/LLM, outcome, queue, backups, integrity, running synthesis and delivery postures…
No input schema was published for this tool.
get_accountReturn this account's state + remaining rate-limit budget. Free read.
`rate_limit` carries {limit, remaining, reset_epoch, reset_at, window_seconds} for
the per-account window, the same budget REST clients read from X-RateLimit-* headers.
Pace a fleet off `remaining` instead of discovering the…Return this account's state + remaining rate-limit budget. Free read. `rate_limit` carries {limit, remaining, reset_epoch, reset_at, window_seconds} for the per-account window, the same budget REST clients read from X-RateLimit-* headers. Pace a fleet off `remaining` instead of discovering the…
| Parameter | Type | Description |
|---|---|---|
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
get_usageReturn the credit balance, per-operation totals, and recent ledger. Free.
Args: recent_limit (1-200, default 50), offset (>=0, pages `recent` past the newest
rows), request_id (scope recent to that call's charges), tag + key_prefix (WP-J
fleet filters), api_key. Returns {credits, totals:{by_ope…Return the credit balance, per-operation totals, and recent ledger. Free. Args: recent_limit (1-200, default 50), offset (>=0, pages `recent` past the newest rows), request_id (scope recent to that call's charges), tag + key_prefix (WP-J fleet filters), api_key. Returns {credits, totals:{by_ope…
| Parameter | Type | Description |
|---|---|---|
| recent_limit | integer | Max recent ledger rows to return, 1-200. Totals are unaffected by this; it only sizes `recent`. |
| offset | integer | Rows to skip before `recent` starts, for paging past the newest page. Page with offset += recent_limit, exactly like list_hooks and list_outcomes; an offset pa… |
| request_id | — | Scope `recent` to the charges of ONE earlier call: pass the request_id that call RETURNED (or its X-Request-Id header), never a freshly minted id. An id that c… |
| tag | — | Filter to rows carrying EXACTLY this fleet tag (exact match, not a substring). Omit for every tag. |
| key_prefix | — | Filter to charges made with ONE api key, identified by the 12-char prefix from list_keys (e.g. vhg_sk_ab12). Omit for every key. |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
export_usageExport ledger, hook, instance, lineage, outcome, profile, and retained-job data.
Free; run BEFORE delete_account. Same JSON body as GET /v1/usage/export; CSV has events.
UNBOUNDED: prefer paged reads on big accounts. Email is masked without admin scope.
Returns account/email/count, ledger, hooks…Export ledger, hook, instance, lineage, outcome, profile, and retained-job data. Free; run BEFORE delete_account. Same JSON body as GET /v1/usage/export; CSV has events. UNBOUNDED: prefer paged reads on big accounts. Email is masked without admin scope. Returns account/email/count, ledger, hooks…
| Parameter | Type | Description |
|---|---|---|
| tag | — | Filter to rows carrying EXACTLY this fleet tag (exact match, not a substring). Omit for every tag. |
| key_prefix | — | Narrow the LEDGER to charges made with ONE api key, identified by the 12-char prefix from list_keys. `hooks`, `hook_instances`, `hook_lineage`, `outcomes`, `jo… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
list_runsEvery call this account was charged for, newest first. Free read.
Recover a lost response in two calls, never re-charged: list_runs(request_id=...)
for the receipt, then follow `hooks_url` for the hooks it produced. Page with
`cursor` (one pass total) or `offset`; stop only when `exhausted` is…Every call this account was charged for, newest first. Free read. Recover a lost response in two calls, never re-charged: list_runs(request_id=...) for the receipt, then follow `hooks_url` for the hooks it produced. Page with `cursor` (one pass total) or `offset`; stop only when `exhausted` is…
| Parameter | Type | Description |
|---|---|---|
| request_id | — | Return only the run with this X-Request-Id (the response header on every call, including errors). This is the lookup for a lost response whose id you still hav… |
| operation | — | Return only runs of this operation: generate_hooks, generate_hooks_batch, remix_hook, score_hook, score_hooks_batch, add_credits. An unknown value returns an e… |
| charged_only | boolean | true (default): only calls that COST credits. false: also include grants and zero-cost calls. |
| limit | integer | Max runs to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation. |
| offset | integer | Number of rows to skip for paging, 0-9223372036854775807. Page with offset += the limit you actually requested; `total` in the response is the unpaged count. T… |
| cursor | integer | Ledger position to resume scanning from (see `next_cursor` on a prior page); not a run count, not an opaque token. Leave at 0 and follow `next_cursor` to walk… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
quoteRead archived generation price and wait metadata without spending. Free.
Validates the retained input schema and computes its historical price ceiling,
balance, cap blocker, and wait metadata. It does not authorize or predict a runnable
operation: generate_hooks is archived and always fails bef…Read archived generation price and wait metadata without spending. Free. Validates the retained input schema and computes its historical price ceiling, balance, cap blocker, and wait metadata. It does not authorize or predict a runnable operation: generate_hooks is archived and always fails bef…
| Parameter | Type | Description |
|---|---|---|
| topic* | string | Historical generation topic, 3-200 chars. This compatibility tool validates stored-client inputs but cannot authorize a writer. |
| platform | string | Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted. |
| count | integer | Historical generation count, 1-25. It drives compatibility price metadata only; the archived writer cannot run. |
| archetypes | — | Restrict generation to these archetype ids (see list_archetypes). Omit to let the engine spread across archetypes, which is what you want unless you are delibe… |
| mode | — | Generation engine and therefore the price: instant (0 base + 1/hook, deterministic templates, sub-second), smart (0 + 2/hook, one LLM call, seconds), research… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
add_creditsCompatibility credit grant (1-10000); beta customer operations are already free.
When VHGENGINE_ADMIN_KEY is configured on the deployment this requires a
matching admin_key argument; otherwise it stays self-serve (unless
VHGENGINE_FREE_CREDITS is off). Idempotent on idempotency_key (replay does…Compatibility credit grant (1-10000); beta customer operations are already free. When VHGENGINE_ADMIN_KEY is configured on the deployment this requires a matching admin_key argument; otherwise it stays self-serve (unless VHGENGINE_FREE_CREDITS is off). Idempotent on idempotency_key (replay does…
| Parameter | Type | Description |
|---|---|---|
| amount* | integer | Compatibility credits to add, 1-10000. Customer operations are free during beta, so this is not required for access. The grant has a per-account balance ceilin… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
| idempotency_key | — | Caller-chosen replay key (any string, unique per intended effect). A repeat call with the SAME key returns the stored result and is NEVER charged twice; the sa… |
| admin_key | — | The deployment's VHGENGINE_ADMIN_KEY. Required ONLY when the operator configured one; omit on a self-serve deployment. A wrong or missing value where one is co… |
list_billing_eventsRecent billing events (usage.recorded, credits.granted, credits.low). Free.
Newest first, paged with limit/offset like list_hooks and list_outcomes. Returns
{events:[{id, event_type, payload, created_at}], limit, offset, total}.
Errors: unauthorized, invalid_request, rate_limited.Recent billing events (usage.recorded, credits.granted, credits.low). Free. Newest first, paged with limit/offset like list_hooks and list_outcomes. Returns {events:[{id, event_type, payload, created_at}], limit, offset, total}. Errors: unauthorized, invalid_request, rate_limited.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Max billing events to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation. |
| offset | integer | Number of rows to skip for paging, 0-9223372036854775807. Page with offset += the limit you actually requested; `total` in the response is the unpaged count. T… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
create_checkoutGet a hosted-checkout link outside beta. Disabled while beta pricing is free.
The REQUIRED idempotency_key creates or replays one durable order and Stripe is
called under an order-derived key, so a retry never mints a second order or
session. Args: pack (from pricing.credit_packs), idempotency_…Get a hosted-checkout link outside beta. Disabled while beta pricing is free. The REQUIRED idempotency_key creates or replays one durable order and Stripe is called under an order-derived key, so a retry never mints a second order or session. Args: pack (from pricing.credit_packs), idempotency_…
| Parameter | Type | Description |
|---|---|---|
| pack* | integer | Which credit pack to buy, given as its CREDITS amount and matched against pricing.credit_packs exactly (not a dollar figure and not an index). A value that is… |
| idempotency_key* | string | REQUIRED caller-chosen replay key for this checkout. The same key replays the same durable order and Stripe session (never a second charge intent); the same ke… |
| success_url | — | Where Stripe sends the browser after a successful payment. At most 2048 characters. Omit to use the deployment's default landing page. |
| cancel_url | — | Where Stripe sends the browser if your human abandons checkout. At most 2048 characters. Omit to use the deployment's default. |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
create_creator_profileCreate an owned, versioned creator profile. Free; admin scope.
At least one creator/audience/stance/fact is required. Returns the exact version,
deny-by-default secondary-use decisions, receipts, and an unverified-attestation
warning. Optional idempotency_key replays safely. Errors: unauthorize…Create an owned, versioned creator profile. Free; admin scope. At least one creator/audience/stance/fact is required. Returns the exact version, deny-by-default secondary-use decisions, receipts, and an unverified-attestation warning. Optional idempotency_key replays safely. Errors: unauthorize…
| Parameter | Type | Description |
|---|---|---|
| display_name* | string | Account-local profile label, 1-100 characters. |
| subject_relationship* | string | self, authorized representative, or organization representative. |
| authority_attested* | boolean | I confirm that I am this creator or am authorized by them to store these declarations and use the selected immutable version when I later make an explicit prof… |
| creator | — | Optional: who is speaking, free text ('wedding videographer, 40k followers, I talk to camera over b-roll of my shoots'). The more the engine knows about the cr… |
| audience | — | Optional: who watches ('engaged couples budgeting'). Aims every hook at a real audience instead of an assumed one. |
| stance | — | Optional: what the creator is for or against, selling, or building, so hooks carry a real position instead of a neutral summary. |
| first_person_facts | — | Optional: facts TRUE of this creator that hooks may assert first-person ('I have filmed 200+ weddings'). The ONLY sanctioned source of personal claims; without… |
| secondary_use | — | Each secondary-use decision is independent and denied by default. These decisions are retained for governance only: generation, scoring, retrieval, and learnin… |
| idempotency_key | — | Caller-chosen replay key (any string, unique per intended effect). A repeat call with the SAME key returns the stored result and is NEVER charged twice; the sa… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
list_creator_profilesList current creator-profile versions, newest changed first. Free; read scope.
Returns {profiles, limit, offset, total}. Each profile carries its immutable
version, declarations, current secondary-use decisions, consent receipts, and
unverified-attestation warning. Errors: unauthorized, forbidd…List current creator-profile versions, newest changed first. Free; read scope. Returns {profiles, limit, offset, total}. Each profile carries its immutable version, declarations, current secondary-use decisions, consent receipts, and unverified-attestation warning. Errors: unauthorized, forbidd…
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Profile page size, 1-100. |
| offset | integer | Number of rows to skip for paging, 0-9223372036854775807. Page with offset += the limit you actually requested; `total` in the response is the unpaged count. T… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
get_creator_profileGet the current or one exact historical creator-profile version. Read scope.
Foreign, deleted, and unknown ids all return the same not_found envelope. Returns
the same profile object as REST. Errors: unauthorized, forbidden, not_found,
invalid_request, rate_limited.Get the current or one exact historical creator-profile version. Read scope. Foreign, deleted, and unknown ids all return the same not_found envelope. Returns the same profile object as REST. Errors: unauthorized, forbidden, not_found, invalid_request, rate_limited.
| Parameter | Type | Description |
|---|---|---|
| profile_id* | string | Account-owned creator profile id returned by create/list profiles. |
| version | — | Exact immutable version; omit for the current version. |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
update_creator_profileAppend a full immutable profile version with compare-and-swap. Admin scope.
expected_version prevents lost updates. Returns version+1, or unchanged:true when
the normalized full snapshot is identical. Optional idempotency_key replays safely.
Errors: unauthorized, forbidden, not_found, conflict,…Append a full immutable profile version with compare-and-swap. Admin scope. expected_version prevents lost updates. Returns version+1, or unchanged:true when the normalized full snapshot is identical. Optional idempotency_key replays safely. Errors: unauthorized, forbidden, not_found, conflict,…
| Parameter | Type | Description |
|---|---|---|
| profile_id* | string | Account-owned creator profile id returned by create/list profiles. |
| expected_version* | integer | Positive immutable profile version. |
| display_name* | string | Account-local profile label, 1-100 characters. |
| subject_relationship* | string | self, authorized representative, or organization representative. |
| authority_attested* | boolean | I confirm that I am this creator or am authorized by them to store these declarations and use the selected immutable version when I later make an explicit prof… |
| creator | — | Optional: who is speaking, free text ('wedding videographer, 40k followers, I talk to camera over b-roll of my shoots'). The more the engine knows about the cr… |
| audience | — | Optional: who watches ('engaged couples budgeting'). Aims every hook at a real audience instead of an assumed one. |
| stance | — | Optional: what the creator is for or against, selling, or building, so hooks carry a real position instead of a neutral summary. |
| first_person_facts | — | Optional: facts TRUE of this creator that hooks may assert first-person ('I have filmed 200+ weddings'). The ONLY sanctioned source of personal claims; without… |
| secondary_use | — | Full replacement decisions; omit for all denied. Each secondary-use decision is independent and denied by default. These decisions are retained for governance… |
| idempotency_key | — | Caller-chosen replay key (any string, unique per intended effect). A repeat call with the SAME key returns the stored result and is NEVER charged twice; the sa… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
delete_creator_profileprivilegedErase profile facts and consent history; retain a retraction marker. Admin scope.
Already committed customer hook outputs are not silently deleted. No profile data is
used for secondary learning or cross-customer retrieval today. One-way replay-key
tombstones prevent delayed keyed writes from r…Erase profile facts and consent history; retain a retraction marker. Admin scope. Already committed customer hook outputs are not silently deleted. No profile data is used for secondary learning or cross-customer retrieval today. One-way replay-key tombstones prevent delayed keyed writes from r…
| Parameter | Type | Description |
|---|---|---|
| profile_id* | string | Account-owned creator profile id returned by create/list profiles. |
| expected_version* | integer | Positive immutable profile version. |
| confirm* | string | Must be exactly "delete" so an accidental call cannot erase it. |
| idempotency_key | — | Caller-chosen replay key (any string, unique per intended effect). A repeat call with the SAME key returns the stored result and is NEVER charged twice; the sa… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
create_keyMint a new named API key; the plaintext is returned ONCE. Requires admin scope.
Delegate safely (WP-SCOPE): optional scopes (subset of read|spend|admin; omit for
full power) + daily_credit_cap (credits/day; omit for uncapped) hand a sub-agent a
key that can only do what you allow. Args: name (1…Mint a new named API key; the plaintext is returned ONCE. Requires admin scope. Delegate safely (WP-SCOPE): optional scopes (subset of read|spend|admin; omit for full power) + daily_credit_cap (credits/day; omit for uncapped) hand a sub-agent a key that can only do what you allow. Args: name (1…
| Parameter | Type | Description |
|---|---|---|
| name | string | Label for the new key, 1-100 chars, shown by list_keys so you can tell delegated keys apart. Defaults to 'key'. |
| scopes | — | Powers the new key gets: read (free reads), spend (charged generate/score/remix), admin (key + account + webhook management). OMIT for a full-power key; pass a… |
| daily_credit_cap | — | Credits this key may spend per UTC day, 1-100000; further charges on it are refused once reached (other keys are unaffected). Omit for uncapped. list_keys repo… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
list_keysList this account's API keys as PREFIXES only (never the raw key). Admin scope.
Returns {keys:[{prefix, name, scopes, daily_credit_cap, spent_today, created_at,
revoked_at}]}, oldest first; revoked_at is null for an active key, scopes lists the
key's grant (WP-SCOPE), spent_today is its credits…List this account's API keys as PREFIXES only (never the raw key). Admin scope. Returns {keys:[{prefix, name, scopes, daily_credit_cap, spent_today, created_at, revoked_at}]}, oldest first; revoked_at is null for an active key, scopes lists the key's grant (WP-SCOPE), spent_today is its credits…
| Parameter | Type | Description |
|---|---|---|
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
revoke_keyRevoke the key with `prefix` (from list_keys): it stops working, others keep working.
Use to kill a leaked or old key. Args: prefix (the 12-char key prefix, e.g.
vhg_sk_ab12), api_key (a DIFFERENT active key to authenticate this call).
Returns {prefix, name, revoked, revoked_at, already_revoked…Revoke the key with `prefix` (from list_keys): it stops working, others keep working. Use to kill a leaked or old key. Args: prefix (the 12-char key prefix, e.g. vhg_sk_ab12), api_key (a DIFFERENT active key to authenticate this call). Returns {prefix, name, revoked, revoked_at, already_revoked…
| Parameter | Type | Description |
|---|---|---|
| prefix* | string | The 12-char key prefix to kill, copied from list_keys (e.g. vhg_sk_ab12), NOT the plaintext key. Revoking is idempotent; you cannot revoke your last active key. |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
delete_accountprivilegedPermanently delete this account. TERMINAL, not reversible. Admin scope (WP-LIFE).
Pass confirm="delete" (guards accidents). Revokes ALL keys and deletes live profile
facts/consent, hooks, webhooks, deliveries, jobs and idempotency; KEEPS bounded profile
retraction markers, the immutable financia…Permanently delete this account. TERMINAL, not reversible. Admin scope (WP-LIFE). Pass confirm="delete" (guards accidents). Revokes ALL keys and deletes live profile facts/consent, hooks, webhooks, deliveries, jobs and idempotency; KEEPS bounded profile retraction markers, the immutable financia…
| Parameter | Type | Description |
|---|---|---|
| confirm* | string | Must be exactly the string "delete". A guard: any other value (or omitting it) fails argument validation before anything is touched, so an accidental invocatio… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
research_hook_evidenceReturn an unpadded portfolio selected deterministically from verified evidence. Hard gates
precede relevance and diversity; views are observed platform views. Openers are
audio_verified, or transcript_grounded with explicit caveats when enabled. Each item has a
grounded idea and later exact payoff,…Return an unpadded portfolio selected deterministically from verified evidence. Hard gates precede relevance and diversity; views are observed platform views. Openers are audio_verified, or transcript_grounded with explicit caveats when enabled. Each item has a grounded idea and later exact payoff,…
| Parameter | Type | Description |
|---|---|---|
| topic* | string | The exact subject the evidence hooks must address. |
| requested_format | — | Optional V1 format preference; omission makes format irrelevant to selection and refusal. |
| schema_version | string | Use hook-research-request-v2 to opt into the V2 contract. |
| formats | — | V2 allowed speaking formats. Omit for the four-format bundle. |
| audience | — | Optional intended viewer whose fit is scored from evidence. |
| problem_or_tension | — | Optional problem or tension that evidence must match. |
| desired_outcome | — | Optional outcome that evidence must support. |
| viewer_action | — | Optional desired viewer action scored from evidence. |
| must_include | — | Exact concepts every admitted item must evidence. |
| must_exclude | — | Concepts every admitted item must evidence as absent. |
| requested_count | integer | V1 maximum verified items, 1-30; above ten returns a durable job to poll. |
| requested_count_v2 | — | V2 maximum verified items, 1-30; omission defaults to 10. |
| minimum_acceptable_count | — | Minimum useful V1 delivery. It may be below requested_count only when allow_partial is true. |
| allow_partial | boolean | When true, a verified count at or above minimum_acceptable_count succeeds. Omit for exact delivery. |
| depth | string | V1 standard supports up to 5 items; deep supports up to 30. |
| source_requirements | — | Per-platform delivery quota policy. If supplied, include TikTok, Instagram, and YouTube exactly once. Required sources use a minimum of 1-30; preferred sources… |
| source_requirements_v2 | — | V2 per-platform quotas; omission prefers all three platforms. |
| minimum_distinct_sources | integer | Minimum distinct admitted platforms, 1-3. |
| requested_language | string | Requested output evidence language: en, fr, es, ar, or ary. |
| accepted_source_languages | — | Verified spoken languages eligible as sources. |
| locale | — | Explicit country, dialect, script, and code-switch policy. |
| freshness | string | Maximum source age: any, 7d, 30d, or 90d. |
| discovery_examples | — | V1 source excerpts guiding new searches, not factual requirements. Follow-ups are separate jobs. |
| allowed_opener_states | — | Opener states this caller accepts. Both public states are accepted by default; transcript_grounded items carry an explicit caveat. |
synthesize_hooksWrite original hooks derived from verified viral source evidence.
Each hook cites one admitted source: verbatim opening, timestamps or explicit nulls
for untimed transcript evidence, observed views with observation time and a versioned
virality receipt whose caveats say views correlate with, not…Write original hooks derived from verified viral source evidence. Each hook cites one admitted source: verbatim opening, timestamps or explicit nulls for untimed transcript evidence, observed views with observation time and a versioned virality receipt whose caveats say views correlate with, not…
| Parameter | Type | Description |
|---|---|---|
| topic* | string | The exact subject the original hooks must address. |
| requested_format* | string | The single speaking format for both sources and hooks. |
| audience | — | Optional intended viewer the hooks are written for. |
| problem_or_tension | — | Optional problem or tension the hooks should open. |
| desired_outcome | — | Optional outcome the video promises. |
| viewer_action | — | Optional desired viewer action. |
| must_include | — | Exact concepts every admitted source must evidence. |
| must_exclude | — | Concepts every admitted source must evidence as absent. |
| requested_count | integer | Original hooks to write, 1-10; one per distinct source. |
| depth | string | standard supports up to 5 hooks; deep supports up to 10. |
| source_requirements_v2 | — | Per-platform source quotas; omission prefers all three. |
| minimum_distinct_sources | integer | Minimum distinct admitted platforms, 1-3. |
| requested_language | string | Requested language: en, fr, es, ar, or ary. |
| accepted_source_languages | — | Verified spoken languages eligible as sources. |
| locale | — | Explicit country, dialect, script, and code-switch policy. |
| freshness | string | Maximum source age: any, 7d, 30d, or 90d. |
| allowed_opener_states | — | Opener states this caller accepts. Both public states are accepted by default; transcript_grounded sources carry an explicit caveat. |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
| idempotency_key | — | Caller-chosen replay key (any string, unique per intended effect). A repeat call with the SAME key returns the stored result and is NEVER charged twice; the sa… |
generate_hooksArchived source-free writer. Use research_hook_evidence instead.
Always fails before model, template, provider, storage, or billing work.
Research requires a real public source video with at least 50,000 observed views,
a canonical link, and an independently audio-verified exact opener.
Errors:…Archived source-free writer. Use research_hook_evidence instead. Always fails before model, template, provider, storage, or billing work. Research requires a real public source video with at least 50,000 observed views, a canonical link, and an independently audio-verified exact opener. Errors:…
| Parameter | Type | Description |
|---|---|---|
| topic* | string | What the hooks are about, 3-200 chars. A concrete subject ('cold plunges for desk workers') scores far better than a bare noun; on research it is also what the… |
| platform | string | Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted. |
| count | integer | How many hooks to generate, 1-25. Drives the price (base + per_hook * hooks_RETURNED) and the pre-flight reservation, so a high count on research is the expens… |
| archetypes | — | Restrict generation to these archetype ids (see list_archetypes). Omit to let the engine spread across archetypes, which is what you want unless you are delibe… |
| style | — | Voice/tone to match, <=200 chars. Honored as a real instruction by smart and research; on instant it only varies which deterministic template fillers are drawn… |
| mode | — | Generation engine and therefore the price: instant (0 base + 1/hook, deterministic templates, sub-second), smart (0 + 2/hook, one LLM call, seconds), research… |
| tags | — | 1-5 lowercase slug tags ([a-z0-9_-], <=40 chars) stamped on this call's usage event so a fleet can attribute spend per campaign. Omit for no tagging. Filter la… |
| verbosity | string | How much of the response envelope to return: minimal (identity, text, score total/source, money, honesty warnings, and any persona/shape), standard (the defaul… |
| deadline_ms | — | Milliseconds you are willing to block, 1000-600000. If the chosen mode's p90 exceeds it the call returns IMMEDIATELY with auto_job:true + a job_id to poll with… |
| creator | — | Optional: who is speaking, free text ('wedding videographer, 40k followers, I talk to camera over b-roll of my shoots'). The more the engine knows about the cr… |
| audience | — | Optional: who watches ('engaged couples budgeting'). Aims every hook at a real audience instead of an assumed one. |
| stance | — | Optional: what the creator is for or against, selling, or building, so hooks carry a real position instead of a neutral summary. |
| first_person_facts | — | Optional: facts TRUE of this creator that hooks may assert first-person ('I have filmed 200+ weddings'). The ONLY sanctioned source of personal claims; without… |
| creator_profile_id | — | Exact owned profile id. Send with creator_profile_version and without inline creator/audience/stance/first_person_facts. |
| creator_profile_version | — | Exact immutable profile version paired with creator_profile_id. |
| clarify | — | Request-sufficiency behaviour: 'ask' returns ONLY clarifying questions (uncharged, nothing generated) - relay them to your human, then re-submit enriched; 'aut… |
| language | — | The language the hooks are WRITTEN in, and the market their evidence is scraped from. en (default) | fr | es | ar (Modern Standard Arabic) | ary (Moroccan Dari… |
| desired_viewer_action | — | What the viewer should do after hearing the hook, such as keep watching, comment, or reconsider a belief, up to 300 characters. Recorded in commission identity… |
| desired_audience_feeling | — | How the audience should feel immediately after the hook, such as understood, curious, or challenged, up to 300 characters. Recorded in commission identity and… |
| requested_market | — | Caller-declared target market or locality, up to 100 characters. This is not inferred or verified and does not override today's language-derived evidence regio… |
| requested_dialect | — | Caller-declared desired dialect or register, up to 100 characters. This is not an observed-language or classifier result. Recorded in commission identity and r… |
| requested_content_format | — | Desired production format: solo_talking_head, podcast, interview, yapping_monologue, voiceover, skit, montage, or other. This is a request, not a claim about a… |
| delivery_constraints | — | Desired spoken performance or cadence, up to 300 characters, distinct from the broader style/voice field. Recorded in commission identity and retained async-jo… |
| hook_length_constraints | — | Desired spoken-hook length, up to 200 characters, for example '8-12 words' or 'under 6 seconds'. Recorded in commission identity and retained async-job snapsho… |
generate_hooks_batchArchived source-free batch writer. Use research_hook_evidence instead.
Always fails before model, template, provider, job, storage, or billing work.
It cannot pad research supply with generated or paraphrased hooks.
Errors: unauthorized; invalid_request with reason unsourced_hook_generation_arch…Archived source-free batch writer. Use research_hook_evidence instead. Always fails before model, template, provider, job, storage, or billing work. It cannot pad research supply with generated or paraphrased hooks. Errors: unauthorized; invalid_request with reason unsourced_hook_generation_arch…
| Parameter | Type | Description |
|---|---|---|
| requests* | array | 1-20 items, each {topic, count?, archetypes?, style?}. Per-item `mode` is rejected: mode, tags, verbosity and idempotency_key are set ONCE for the whole batch.… |
| platform | string | Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted. |
| mode | — | Generation engine and therefore the price: instant (0 base + 1/hook, deterministic templates, sub-second), smart (0 + 2/hook, one LLM call, seconds), research… |
| tags | — | 1-5 lowercase slug tags ([a-z0-9_-], <=40 chars) stamped on this call's usage event so a fleet can attribute spend per campaign. Omit for no tagging. Filter la… |
| verbosity | string | How much of the response envelope to return: minimal (identity, text, score total/source, money, honesty warnings, and any persona/shape), standard (the defaul… |
| creator | — | Optional: who is speaking, free text ('wedding videographer, 40k followers, I talk to camera over b-roll of my shoots'). The more the engine knows about the cr… |
| audience | — | Optional: who watches ('engaged couples budgeting'). Aims every hook at a real audience instead of an assumed one. |
| stance | — | Optional: what the creator is for or against, selling, or building, so hooks carry a real position instead of a neutral summary. |
| first_person_facts | — | Optional: facts TRUE of this creator that hooks may assert first-person ('I have filmed 200+ weddings'). The ONLY sanctioned source of personal claims; without… |
| creator_profile_id | — | Exact owned profile id. Send with creator_profile_version and without inline creator/audience/stance/first_person_facts. |
| creator_profile_version | — | Exact immutable profile version paired with creator_profile_id. |
| clarify | — | Request-sufficiency behaviour: 'ask' returns ONLY clarifying questions (uncharged, nothing generated) - relay them to your human, then re-submit enriched; 'aut… |
| language | — | The language the hooks are WRITTEN in, and the market their evidence is scraped from. en (default) | fr | es | ar (Modern Standard Arabic) | ary (Moroccan Dari… |
| desired_viewer_action | — | What the viewer should do after hearing the hook, such as keep watching, comment, or reconsider a belief, up to 300 characters. Recorded in commission identity… |
| desired_audience_feeling | — | How the audience should feel immediately after the hook, such as understood, curious, or challenged, up to 300 characters. Recorded in commission identity and… |
| requested_market | — | Caller-declared target market or locality, up to 100 characters. This is not inferred or verified and does not override today's language-derived evidence regio… |
| requested_dialect | — | Caller-declared desired dialect or register, up to 100 characters. This is not an observed-language or classifier result. Recorded in commission identity and r… |
| requested_content_format | — | Desired production format: solo_talking_head, podcast, interview, yapping_monologue, voiceover, skit, montage, or other. This is a request, not a claim about a… |
| delivery_constraints | — | Desired spoken performance or cadence, up to 300 characters, distinct from the broader style/voice field. Recorded in commission identity and retained async-jo… |
| hook_length_constraints | — | Desired spoken-hook length, up to 200 characters, for example '8-12 words' or 'under 6 seconds'. Recorded in commission identity and retained async-job snapsho… |
| footage_constraints | — | Up to 10 caller-declared filming or edit constraints, each up to 200 characters. Recorded in commission identity and retained async-job snapshots. It does not… |
| caller_confirmed_constraints | — | Up to 10 caller-confirmed request constraints from a prior clarification round, each up to 300 characters. Runtime-generated questions and model assumptions ar… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
| idempotency_key | — | Caller-chosen replay key (any string, unique per intended effect). A repeat call with the SAME key returns the stored result and is NEVER charged twice; the sa… |
score_hookScore any hook text on 5 dimensions with rewrite tips. Free during beta.
Deterministic heuristic scorer (no LLM). Args: text (3-300), platform, topic
(optional, reproduces generate's score via the verbatim-echo penalty), tags (1-5
fleet slugs, WP-J), verbosity (full keeps per-dimension attribut…Score any hook text on 5 dimensions with rewrite tips. Free during beta. Deterministic heuristic scorer (no LLM). Args: text (3-300), platform, topic (optional, reproduces generate's score via the verbatim-echo penalty), tags (1-5 fleet slugs, WP-J), verbosity (full keeps per-dimension attribut…
| Parameter | Type | Description |
|---|---|---|
| text* | string | The hook line to score, 3-300 chars. Any text is accepted (it does not have to be one Hook Detector generated) and it is never persisted as a hook you own. |
| platform | string | Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted. |
| topic | — | The subject this text was written FOR. Pass the SAME topic string a generate call used and this reproduces the exact score.total that generate served for the h… |
| tags | — | 1-5 lowercase slug tags ([a-z0-9_-], <=40 chars) stamped on this call's usage event so a fleet can attribute spend per campaign. Omit for no tagging. Filter la… |
| verbosity | string | How much of the response envelope to return: minimal (identity, text, score total/source, money, honesty warnings, and any persona/shape), standard (the defaul… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
| idempotency_key | — | Caller-chosen replay key (any string, unique per intended effect). A repeat call with the SAME key returns the stored result and is NEVER charged twice; the sa… |
score_hooks_batchScore many hooks ranked with `best`, or compare named SETS. Free during beta.
All-or-nothing charge. Plain: texts (1-25, each 3-300 chars). Self-test (E13):
compare=true + sets (2-4 named lists, <=25 texts total) INSTEAD of texts -> per-set
rankings + avg_score + winner + an honest winner_summa…Score many hooks ranked with `best`, or compare named SETS. Free during beta. All-or-nothing charge. Plain: texts (1-25, each 3-300 chars). Self-test (E13): compare=true + sets (2-4 named lists, <=25 texts total) INSTEAD of texts -> per-set rankings + avg_score + winner + an honest winner_summa…
| Parameter | Type | Description |
|---|---|---|
| texts | — | 1-25 hook lines (3-300 chars each) to score and rank. Use this OR sets, never both: texts is the plain ranked mode, sets is the compare mode. Customer charge i… |
| platform | string | Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted. |
| compare | boolean | Switch on compare mode, which requires `sets` and returns per-set rankings + a winner instead of one flat ranking. Leave false for the ordinary texts ranking. |
| sets | — | Compare mode input: 2-4 NAMED variant lists, e.g. {"curiosity": ["..."], "contrarian": ["..."]}, each 1-25 texts and <=25 texts across all sets. Requires compa… |
| topic | — | What the hooks are about, 3-200 chars. Supply it to score these lines the way they were generated: the scorer penalises a line that only echoes its own topic b… |
| tags | — | 1-5 lowercase slug tags ([a-z0-9_-], <=40 chars) stamped on this call's usage event so a fleet can attribute spend per campaign. Omit for no tagging. Filter la… |
| verbosity | string | How much of the response envelope to return: minimal (identity, text, score total/source, money, honesty warnings, and any persona/shape), standard (the defaul… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
| idempotency_key | — | Caller-chosen replay key (any string, unique per intended effect). A repeat call with the SAME key returns the stored result and is NEVER charged twice; the sa… |
remix_hookArchived source-free remix writer. Use research_hook_evidence instead.
Always fails before rewriting, model, storage, or billing work.
An extracted source hook cannot be replaced by generated or paraphrased copy.
Errors: unauthorized; invalid_request with reason unsourced_hook_generation_archive…Archived source-free remix writer. Use research_hook_evidence instead. Always fails before rewriting, model, storage, or billing work. An extracted source hook cannot be replaced by generated or paraphrased copy. Errors: unauthorized; invalid_request with reason unsourced_hook_generation_archive…
| Parameter | Type | Description |
|---|---|---|
| text | — | The existing hook to rewrite, 3-300 chars. Its subject is kept; only the angle moves to target_archetype. Pass this OR `hook_id`, never both and never neither. |
| target_archetype | — | Archetype id to rewrite INTO (see list_archetypes for ids and their psychology). `archetype` is an accepted alias for this argument; one of the two is required… |
| count | integer | Archived compatibility count, 1-5. Remix fails before work or customer charge. |
| hook_id | — | Remix a hook you ALREADY bought, by the id a generate/batch/remix response returned (also listed by list_hooks): the stored text is looked up for you, so you d… |
| archetype | — | Alias for `target_archetype`, spelled the way every hook object in every response spells it. Send either one; sending both is fine only if they are equal, and… |
| platform | — | The platform whose SCORING WINDOW grades these variants, as on generate_hooks and score_hook: LinkedIn's ideal hook length is 10-18 words against 8-14 elsewher… |
| topic | — | The subject the hook was written FOR, scored as on score_hook: the verbatim-echo penalty only fires when the scorer is told the topic, so a hook (or a variant)… |
| tags | — | 1-5 lowercase slug tags ([a-z0-9_-], <=40 chars) stamped on this call's usage event so a fleet can attribute spend per campaign. Omit for no tagging. Filter la… |
| verbosity | string | How much of the response envelope to return: minimal (identity, text, score total/source, money, honesty warnings, and any persona/shape), standard (the defaul… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
| idempotency_key | — | Caller-chosen replay key (any string, unique per intended effect). A repeat call with the SAME key returns the stored result and is NEVER charged twice; the sa… |
list_hooksList the hooks this account has bought, newest first. Free (WP-G).
Retrievable for 90 days. Args: mode (instant|smart|research|remix, or a generate
alias such as template/search), since (ISO timestamp), tag (exact fleet-tag match),
topic (substring), request_id (recover one charged call's hooks…List the hooks this account has bought, newest first. Free (WP-G). Retrievable for 90 days. Args: mode (instant|smart|research|remix, or a generate alias such as template/search), since (ISO timestamp), tag (exact fleet-tag match), topic (substring), request_id (recover one charged call's hooks…
| Parameter | Type | Description |
|---|---|---|
| mode | — | Filter to hooks bought from this engine. Canonical stored values: instant|smart|research|remix; the generate aliases (template|off|quick, llm|on|fast, search|d… |
| since | — | Return only rows created at or after this UTC timestamp. Compared LEXICALLY against stored 'YYYY-MM-DDTHH:MM:SSZ' values, so pass that exact format (a date-onl… |
| tag | — | Filter to hooks carrying EXACTLY this fleet tag: a lowercase slug of 1-40 chars of [a-z0-9_-], matched LITERALLY. `_` is a legal tag character and is NOT a wil… |
| topic | — | Case-insensitive SUBSTRING match against the topic a hook was generated for (unlike `tag`, which is exact). Omit for every topic. |
| request_id | — | Return ONLY the hooks produced by this request_id. This is the exact recovery filter: an agent that lost a generate response reads the request_id off list_runs… |
| unreported | — | true = only hooks with no outcome yet, i.e. the ones a first report_outcome can still earn a reward on. false = only hooks already reported. Omit for both. |
| limit | integer | Max hooks to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation. |
| offset | integer | Number of rows to skip for paging, 0-9223372036854775807. Page with offset += the limit you actually requested; `total` in the response is the unpaged count. T… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
get_hookFetch one bought hook in full, including its parsed score. Free (WP-G).
Account-scoped: a foreign or unknown id is not_found (no existence leak). Args:
hook_id (from a generate/batch/remix response or list_hooks), api_key. Returns
{hook_id, text, archetype, claim_type, mode, platform, topic, sc…Fetch one bought hook in full, including its parsed score. Free (WP-G). Account-scoped: a foreign or unknown id is not_found (no existence leak). Args: hook_id (from a generate/batch/remix response or list_hooks), api_key. Returns {hook_id, text, archetype, claim_type, mode, platform, topic, sc…
| Parameter | Type | Description |
|---|---|---|
| hook_id* | string | The hook's id, as returned in the `hooks[].hook_id` of a generate/batch/remix response or by list_hooks. Account-scoped: an id you do not own reads as not_foun… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
list_outcomesList the posted outcomes THIS account has reported, newest first. Free (WP-LIFE).
Retrieve submitted telemetry in bulk. Args: platform
(tiktok|instagram|youtube|x|linkedin|other), since (ISO timestamp), hook_id,
limit (1-200, default 50), offset (>=0), api_key. Rows include the feature snapshot…List the posted outcomes THIS account has reported, newest first. Free (WP-LIFE). Retrieve submitted telemetry in bulk. Args: platform (tiktok|instagram|youtube|x|linkedin|other), since (ISO timestamp), hook_id, limit (1-200, default 50), offset (>=0), api_key. Rows include the feature snapshot…
| Parameter | Type | Description |
|---|---|---|
| platform | — | Filter to outcomes reported for one platform. Omit for all. |
| since | — | Return only rows created at or after this UTC timestamp. Compared LEXICALLY against stored 'YYYY-MM-DDTHH:MM:SSZ' values, so pass that exact format (a date-onl… |
| hook_id | — | Filter to the outcomes reported against ONE hook (its id from list_hooks / a generate response). Omit for every hook. |
| limit | integer | Max outcomes to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation. |
| offset | integer | Number of rows to skip for paging, 0-9223372036854775807. Page with offset += the limit you actually requested; `total` in the response is the unpaged count. T… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
report_outcomeReport what a bought hook actually did once posted. FREE (WP-H).
Caller-supplied, unverified, and not used by generation/scoring/retrieval today.
Retained for possible future calibration; no view prediction. Args: hook_id,
platform (tiktok|instagram|youtube|x|linkedin|other), posted_at, views/li…Report what a bought hook actually did once posted. FREE (WP-H). Caller-supplied, unverified, and not used by generation/scoring/retrieval today. Retained for possible future calibration; no view prediction. Args: hook_id, platform (tiktok|instagram|youtube|x|linkedin|other), posted_at, views/li…
| Parameter | Type | Description |
|---|---|---|
| hook_id* | string | Which bought hook this result belongs to: the hook_id from a generate/batch/remix response or list_hooks. Must be a hook you own. |
| platform* | string | Where the hook was actually posted. Required. |
| posted_at* | string | When it went live, ISO-8601 UTC ('YYYY-MM-DDTHH:MM:SSZ'). May be in the past; more than 48h in the FUTURE is invalid_request. |
| views* | integer | Views the post had accrued at report time, >=0. Required: caller-supplied and not independently verified; retained as the primary measure for possible future c… |
| likes | — | Likes at report time, >=0. Omit if you cannot read it. |
| retention_pct | — | Average view-through as a PERCENT, 0-100 (not a 0-1 fraction). Omit if the platform does not expose it. |
| url | — | Public http(s) URL of the post, for your own audit trail. Must carry a host; omit entirely rather than passing a placeholder. |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
| idempotency_key | — | Caller-chosen replay key (any string, unique per intended effect). A repeat call with the SAME key returns the stored result and is NEVER charged twice; the sa… |
start_generate_jobArchived source-free writer job. Use research_hook_evidence instead.
Always fails before a job, model, provider, storage, or billing work.
Async execution cannot bypass source-video, view, link, and excerpt proof.
Errors: unauthorized; invalid_request with reason unsourced_hook_generation_archiv…Archived source-free writer job. Use research_hook_evidence instead. Always fails before a job, model, provider, storage, or billing work. Async execution cannot bypass source-video, view, link, and excerpt proof. Errors: unauthorized; invalid_request with reason unsourced_hook_generation_archiv…
| Parameter | Type | Description |
|---|---|---|
| topic | — | Single subject for the job, 3-200 chars. Pass EITHER this or `topics`, never both and never neither. |
| topics | — | 1-20 subjects run as ONE job with ONE atomic charge; the result is the batch envelope instead of a single generate body. Pass EITHER this or `topic`. |
| platform | string | Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted. |
| count | integer | Hooks per topic, 1-25. With `topics` this applies to every subject, so the job's cost scales with count * len(topics). |
| archetypes | — | Restrict generation to these archetype ids (see list_archetypes). Omit to let the engine spread across archetypes, which is what you want unless you are delibe… |
| style | — | Voice/tone to match, <=200 chars. Honored as a real instruction by smart and research; on instant it only varies which deterministic template fillers are drawn… |
| mode | — | Generation engine and therefore the price: instant (0 base + 1/hook, deterministic templates, sub-second), smart (0 + 2/hook, one LLM call, seconds), research… |
| tags | — | 1-5 lowercase slug tags ([a-z0-9_-], <=40 chars) stamped on this call's usage event so a fleet can attribute spend per campaign. Omit for no tagging. Filter la… |
| creator | — | Optional: who is speaking, free text ('wedding videographer, 40k followers, I talk to camera over b-roll of my shoots'). The more the engine knows about the cr… |
| audience | — | Optional: who watches ('engaged couples budgeting'). Aims every hook at a real audience instead of an assumed one. |
| stance | — | Optional: what the creator is for or against, selling, or building, so hooks carry a real position instead of a neutral summary. |
| first_person_facts | — | Optional: facts TRUE of this creator that hooks may assert first-person ('I have filmed 200+ weddings'). The ONLY sanctioned source of personal claims; without… |
| creator_profile_id | — | Exact owned profile id. Send with creator_profile_version and without inline creator/audience/stance/first_person_facts. |
| creator_profile_version | — | Exact immutable profile version paired with creator_profile_id. |
| clarify | — | Request-sufficiency behaviour: 'ask' returns ONLY clarifying questions (uncharged, nothing generated) - relay them to your human, then re-submit enriched; 'aut… |
| language | — | The language the hooks are WRITTEN in, and the market their evidence is scraped from. en (default) | fr | es | ar (Modern Standard Arabic) | ary (Moroccan Dari… |
| desired_viewer_action | — | What the viewer should do after hearing the hook, such as keep watching, comment, or reconsider a belief, up to 300 characters. Recorded in commission identity… |
| desired_audience_feeling | — | How the audience should feel immediately after the hook, such as understood, curious, or challenged, up to 300 characters. Recorded in commission identity and… |
| requested_market | — | Caller-declared target market or locality, up to 100 characters. This is not inferred or verified and does not override today's language-derived evidence regio… |
| requested_dialect | — | Caller-declared desired dialect or register, up to 100 characters. This is not an observed-language or classifier result. Recorded in commission identity and r… |
| requested_content_format | — | Desired production format: solo_talking_head, podcast, interview, yapping_monologue, voiceover, skit, montage, or other. This is a request, not a claim about a… |
| delivery_constraints | — | Desired spoken performance or cadence, up to 300 characters, distinct from the broader style/voice field. Recorded in commission identity and retained async-jo… |
| hook_length_constraints | — | Desired spoken-hook length, up to 200 characters, for example '8-12 words' or 'under 6 seconds'. Recorded in commission identity and retained async-job snapsho… |
| footage_constraints | — | Up to 10 caller-declared filming or edit constraints, each up to 200 characters. Recorded in commission identity and retained async-job snapshots. It does not… |
get_jobPoll an async job: status, real engine stage, progress, ETA, result/error.
Poll after poll_after_seconds until status is "succeeded" (result holds the full
generate body) or "failed" (error holds the typed envelope). Only the owning
account can read a job; a foreign/unknown id is not_found (no…Poll an async job: status, real engine stage, progress, ETA, result/error. Poll after poll_after_seconds until status is "succeeded" (result holds the full generate body) or "failed" (error holds the typed envelope). Only the owning account can read a job; a foreign/unknown id is not_found (no…
| Parameter | Type | Description |
|---|---|---|
| job_id* | string | The job's id, as returned by start_generate_job (or by a generate_hooks call that auto-jobbed on deadline_ms). Account-scoped: an id you do not own reads as no… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
| result_view | string | Use compact for source evidence and costs with less response text. Full preserves every audit receipt. Views never rerun or recharge research. |
wait_for_jobBlock until a job is terminal, then return it. Free, bounded, no poll loop.
Returns the chosen get_job result_view plus timed_out, waited_ms and polls; branch on
`status` exactly as you would with get_job. timed_out:true is NOT a failure, it
means the budget ran out: call again with the SAME jo…Block until a job is terminal, then return it. Free, bounded, no poll loop. Returns the chosen get_job result_view plus timed_out, waited_ms and polls; branch on `status` exactly as you would with get_job. timed_out:true is NOT a failure, it means the budget ran out: call again with the SAME jo…
| Parameter | Type | Description |
|---|---|---|
| job_id* | string | The job to wait on, as returned by start_generate_job (or by a generate_hooks call that auto-jobbed on deadline_ms). Account-scoped: an id you do not own reads… |
| timeout_seconds | integer | How long to block, 1-300 seconds. Keep it BELOW your own MCP client's request timeout, or the client gives up before this tool answers. Running out is not an e… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
| result_view | string | Use compact for source evidence and costs with less response text. Full preserves every audit receipt. Views never rerun or recharge research. |
cancel_jobCancel a job that is STILL QUEUED. Free, repeatable, never refunds.
ALWAYS branch on `cancelled`; reason + next_action say what to do. A queued job
was never charged (the worker charges), so credits_refunded is always 0. A RUNNING
job cannot be stopped: it finishes, CHARGES and persists. Cancel…Cancel a job that is STILL QUEUED. Free, repeatable, never refunds. ALWAYS branch on `cancelled`; reason + next_action say what to do. A queued job was never charged (the worker charges), so credits_refunded is always 0. A RUNNING job cannot be stopped: it finishes, CHARGES and persists. Cancel…
| Parameter | Type | Description |
|---|---|---|
| job_id* | string | The job to cancel. Account-scoped: an id you do not own reads as not_found, exactly like get_job. |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
list_jobsList this account's jobs, newest first (summaries without the result blob).
Args: limit (1-200, default 50), offset (>=0), api_key. Returns {jobs:[{job_id,
status, stage, progress_pct, created_at, started_at, finished_at}], limit,
offset, total}. Errors: unauthorized, rate_limited.List this account's jobs, newest first (summaries without the result blob). Args: limit (1-200, default 50), offset (>=0), api_key. Returns {jobs:[{job_id, status, stage, progress_pct, created_at, started_at, finished_at}], limit, offset, total}. Errors: unauthorized, rate_limited.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Max jobs to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation. |
| offset | integer | Number of rows to skip for paging, 0-9223372036854775807. Page with offset += the limit you actually requested; `total` in the response is the unpaged count. T… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
set_webhookRegister (or replace) this account's webhook; the secret is returned ONCE. Admin scope.
Hook Detector POSTs signed job.succeeded/job.failed/credits.low (WP-M). `url` https, no
creds, public host; re-registering ROTATES the secret (a repeat call is not a no-op).
Verify via X-VHG-Signature: sha25…Register (or replace) this account's webhook; the secret is returned ONCE. Admin scope. Hook Detector POSTs signed job.succeeded/job.failed/credits.low (WP-M). `url` https, no creds, public host; re-registering ROTATES the secret (a repeat call is not a no-op). Verify via X-VHG-Signature: sha25…
| Parameter | Type | Description |
|---|---|---|
| url* | string | https:// endpoint that will receive signed event POSTs. Must be a public host with no embedded credentials. Re-registering ANY url rotates the signing secret,… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
get_webhookThis account's webhook (url + last delivery status; never the secret). Free read.
Args: api_key (read scope). Cost=free. Returns {url, created_at, last_delivery_status,
last_delivery_at, events}. Errors: unauthorized, not_found (none registered),
rate_limited.This account's webhook (url + last delivery status; never the secret). Free read. Args: api_key (read scope). Cost=free. Returns {url, created_at, last_delivery_status, last_delivery_at, events}. Errors: unauthorized, not_found (none registered), rate_limited.
| Parameter | Type | Description |
|---|---|---|
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
delete_webhookprivilegedRemove this account's webhook (WP-M). Admin scope.
Args: api_key (admin scope). Cost=free. Returns {deleted: true}. Errors: unauthorized,
forbidden, not_found (none registered), rate_limited.Remove this account's webhook (WP-M). Admin scope. Args: api_key (admin scope). Cost=free. Returns {deleted: true}. Errors: unauthorized, forbidden, not_found (none registered), rate_limited.
| Parameter | Type | Description |
|---|---|---|
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
list_webhook_deliveriesList this account's webhook deliveries, newest first. Free read (WP-HOOKS).
Verify your receiver end-to-end (a webhook.test ping is enqueued at registration) and
diagnose failures without waiting out a real event. Args: status (pending|retrying|
delivered|dead|retired), limit (1-200, default 50…List this account's webhook deliveries, newest first. Free read (WP-HOOKS). Verify your receiver end-to-end (a webhook.test ping is enqueued at registration) and diagnose failures without waiting out a real event. Args: status (pending|retrying| delivered|dead|retired), limit (1-200, default 50…
| Parameter | Type | Description |
|---|---|---|
| status | — | Filter to deliveries in this state: pending (queued, not yet attempted), retrying (failed, backing off), delivered (2xx), dead (retries exhausted; redrive_webh… |
| limit | integer | Max deliveries to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation. |
| offset | integer | Number of rows to skip for paging, 0-9223372036854775807. Page with offset += the limit you actually requested; `total` in the response is the unpaged count. T… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
redrive_webhook_deliveryRequeue a dead-lettered webhook delivery: reset to pending, due now. Admin scope.
Valid ONLY on a `dead` delivery (a live receiver that exhausted its retries); any other
status is a 409 conflict and a delivery you do not own is not_found. It re-attempts
through the normal pipeline and, if it di…Requeue a dead-lettered webhook delivery: reset to pending, due now. Admin scope. Valid ONLY on a `dead` delivery (a live receiver that exhausted its retries); any other status is a 409 conflict and a delivery you do not own is not_found. It re-attempts through the normal pipeline and, if it di…
| Parameter | Type | Description |
|---|---|---|
| delivery_id* | string | The delivery to requeue, from list_webhook_deliveries. Only a `dead` row can be redriven; any other status is a conflict and a delivery you do not own is not_f… |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
get_activitySee what this account's agents are doing: in-flight ops + recent ops. Free.
`in_flight` merges the live-ops registry (real stage/pct/eta mid-run) with your
queued/running jobs; `recent` is the last completed charged ops. Every row has a
human-readable message. The REST surface also offers an SS…See what this account's agents are doing: in-flight ops + recent ops. Free. `in_flight` merges the live-ops registry (real stage/pct/eta mid-run) with your queued/running jobs; `recent` is the last completed charged ops. Every row has a human-readable message. The REST surface also offers an SS…
| Parameter | Type | Description |
|---|---|---|
| recent_limit | integer | Max completed rows in `recent`, 1-100. Does not limit `in_flight`, which always shows everything currently running. |
| api_key | — | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (th… |
45 of 45 tools published a description.
Tool names and descriptions are written by the publisher and shown verbatim as inert text. They are the strings an MCP client passes to a model, so Forge scans them for prompt-injection patterns — any finding appears with the security scan above. “Privileged” is a keyword match on the tool name, not an audit of what the tool does: a benign-sounding name can still do anything.
Agents-first viral-hook engine: generate, score, and remix short-form hooks over MCP.
+ 5 more observed on this entry.
Linked names open Forge’s index of every entry observed exposing that tool. Browse all indexed tools.
This entry publishes no npm package, so Forge has no dependency tree for it. That is a gap in coverage — not a statement that it has no dependencies.