signup

Create an account and return your API key exactly once. No auth needed. The entry point: an agent with nothing calls this and is productive immediately (no CAPTCHA); new accounts get 500 credits. Args: name (1-100 chars), email (OPTIONAL contact hint, never required), idempotency_key (replay returns the SAME account, never re-grants). Returns {account_id, api_key (shown ONCE), api_key_prefix, credits, created_at, note, next_steps, docs}. Cost: free. Errors: invalid_request, idempotency_conflict, rate_limited.

Parameters3

name	string	optional
email	any	optional
idempotency_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "default": "agent",
      "title": "Name",
      "type": "string"
    },
    "email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Email"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "title": "signupArguments"
}

getting_started

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}.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "getting_startedArguments"
}

list_archetypes

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=...).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "list_archetypesArguments"
}

pricing

The machine-readable price list, with per-mode expected_wait. Free, no auth. Returns {unit, usd_per_credit (0 while credits are free), operations, pricing_modes:{instant:{base:0,per_hook:1},smart:{base:0,per_hook:2}, research:{base:10,per_hook:4}} each with a formula, expected_wait, signup_grant, low_balance_threshold}. A generate charge is base + per_hook * hooks_returned; these are the exact constants the charge path uses.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "pricingArguments"
}

get_estimates

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}}}.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "get_estimatesArguments"
}

health

Deep health: a real DB ping plus whether an LLM key is configured. Free. Returns {status ("ok"|"unavailable"), version, time, llm_configured, outcomes_reported_total (the compounding-corpus counter, a 60s-cached COUNT)}. llm_configured is a pure config read; this NEVER makes a live LLM call.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "healthArguments"
}

get_account

Return this account's state (no API key echoed back). Free read. Returns {account_id, name, credits, api_key_prefix, created_at}. Errors: unauthorized, rate_limited.

Parameters1

api_key

any

optional

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "get_accountArguments"
}

get_usage

Return the credit balance, per-operation totals, and recent ledger. Free. Args: recent_limit (1-200, default 50), request_id (scope recent to that call's charges), tag + key_prefix (WP-J fleet filters), api_key. Returns {credits, totals:{by_operation}, recent:[...]} (each row carries key_prefix; tags in metadata). Errors: unauthorized, rate_limited.

Parameters5

recent_limit	integer	optional
request_id	any	optional
tag	any	optional
key_prefix	any	optional
api_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "recent_limit": {
      "default": 50,
      "title": "Recent Limit",
      "type": "integer"
    },
    "request_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Request Id"
    },
    "tag": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tag"
    },
    "key_prefix": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Key Prefix"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "get_usageArguments"
}

add_credits

Top up your credit balance (1-10000). Self-serve by default. 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 NOT grant twice). Returns {credits (new balance), granted}. Errors: unauthorized (missing/wrong admin key or self-serve disabled), invalid_request (amount range / balance ceiling), idempotency_conflict, rate_limited.

Parameters4

amount	integer	required
api_key	any	optional
idempotency_key	any	optional
admin_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "amount": {
      "title": "Amount",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    },
    "admin_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Admin Key"
    }
  },
  "required": [
    "amount"
  ],
  "title": "add_creditsArguments"
}

create_checkout

Get a Stripe hosted-checkout link for a credit pack. You never touch a card (WP-PAY). Hand the returned checkout_url to your human; the webhook credits you after they pay. Args: pack (a credits amount from pricing.credit_packs), success_url/cancel_url (optional), api_key (spend scope). Returns {checkout_url, pack, credits, usd_cents, expires_at}. Errors: unauthorized, forbidden, invalid_request (bad pack), payments_disabled (503; use add_credits), rate_limited.

Parameters4

pack	integer	required
success_url	any	optional
cancel_url	any	optional
api_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "pack": {
      "title": "Pack",
      "type": "integer"
    },
    "success_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Success Url"
    },
    "cancel_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cancel Url"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "pack"
  ],
  "title": "create_checkoutArguments"
}

create_key

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-100), api_key (an admin-scoped key). Returns {api_key (store it), prefix, name, scopes, daily_credit_cap, created_at}. Errors: unauthorized, forbidden, invalid_request, rate_limited.

Parameters4

name	string	optional
scopes	any	optional
daily_credit_cap	any	optional
api_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "default": "key",
      "title": "Name",
      "type": "string"
    },
    "scopes": {
      "anyOf": [
        {
          "items": {
            "enum": [
              "read",
              "spend",
              "admin"
            ],
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scopes"
    },
    "daily_credit_cap": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Daily Credit Cap"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "create_keyArguments"
}

list_keys

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 spent since UTC midnight. Your signup key shows as name "default". Errors: unauthorized, forbidden, rate_limited.

Parameters1

api_key

any

optional

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "list_keysArguments"
}

revoke_key

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}. You cannot revoke your LAST active key (create a replacement first). Requires the admin scope. Errors: unauthorized, forbidden, invalid_request (last key), not_found, rate_limited.

Parameters2

prefix	string	required
api_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "prefix": {
      "title": "Prefix",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "prefix"
  ],
  "title": "revoke_keyArguments"
}

delete_account

Permanently delete this account. TERMINAL, not reversible. Admin scope (WP-LIFE). Pass confirm="delete" (guards an accidental call). Revokes ALL your keys (every key 401s), deletes your hooks, webhook, deliveries, jobs, and idempotency rows, KEEPS the immutable financial ledger, and ANONYMIZES your outcomes into the shared corpus. A second call 401s naturally. Export first: GET /v1/usage/export?format=json. Returns {deleted, retained:{financial_events, anonymized_outcomes}, note}. Errors: unauthorized, forbidden, invalid_request, rate_limited.

Parameters2

confirm	string	required
api_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "confirm": {
      "const": "delete",
      "title": "Confirm",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "confirm"
  ],
  "title": "delete_accountArguments"
}

generate_hooks

Generate ranked, scored viral hooks for a topic. Charged by mode. Cost = base + per_hook * hooks_returned: instant 0+1, smart 0+2, research 10+4 (~50 at count=10); a pre-flight gate reserves base + per_hook * count, never billing a broke account. Deterministic only in instant; verbosity minimal|standard|full shapes the response; tags = slugs; a progressToken streams stages; deadline_ms (1000-600000) auto-jobs a slow mode past its p90 (auto_job:true). Returns hooks + mode_used + pricing + money + request_id. Errors: unauthorized, invalid_request, llm_unavailable, insufficient_credits, rate_limited.

Parameters11

topic	string	required
platform	string	optional
count	integer	optional
archetypes	any	optional
style	any	optional
mode	any	optional
tags	any	optional
verbosity	string	optional
deadline_ms	any	optional
api_key	any	optional
idempotency_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "topic": {
      "maxLength": 200,
      "minLength": 3,
      "title": "Topic",
      "type": "string"
    },
    "platform": {
      "default": "tiktok",
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "linkedin"
      ],
      "title": "Platform",
      "type": "string"
    },
    "count": {
      "default": 10,
      "maximum": 25,
      "minimum": 1,
      "title": "Count",
      "type": "integer"
    },
    "archetypes": {
      "anyOf": [
        {
          "items": {
            "enum": [
              "curiosity_gap",
              "contrarian",
              "data_shock",
              "story",
              "transformation",
              "listicle",
              "authority",
              "urgency"
            ],
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Archetypes"
    },
    "style": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Style"
    },
    "mode": {
      "anyOf": [
        {
          "enum": [
            "instant",
            "template",
            "off",
            "quick",
            "smart",
            "llm",
            "on",
            "fast",
            "research",
            "search",
            "deep",
            "deep_research",
            "auto"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Mode"
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "maxLength": 40,
            "minLength": 1,
            "pattern": "^[a-z0-9_-]+$",
            "type": "string"
          },
          "maxItems": 5,
          "minItems": 1,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tags"
    },
    "verbosity": {
      "default": "standard",
      "enum": [
        "minimal",
        "standard",
        "full"
      ],
      "title": "Verbosity",
      "type": "string"
    },
    "deadline_ms": {
      "anyOf": [
        {
          "maximum": 600000,
          "minimum": 1000,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Deadline Ms"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "topic"
  ],
  "title": "generate_hooksArguments"
}

generate_hooks_batch

Generate hooks for many topics in ONE call, charged all-or-nothing. One transaction: over-balance charges nothing; each item bills base + per_hook * hooks_returned for the engine that ran (divergent tiers -> pricing_mode "mixed"). One mode + idempotency_key + tags cover the batch; verbosity applies to every item; a progressToken streams item i/n. Returns {results:[{topic, hooks, pricing_mode, price_per_hook, base_price, credits, timing}], mode_used, pricing_mode, credits_charged, credits_remaining, request_id}. Errors: unauthorized, invalid_request, llm_unavailable, insufficient_credits, rate_limited.

Parameters7

requests	array	required
platform	string	optional
mode	any	optional
tags	any	optional
verbosity	string	optional
api_key	any	optional
idempotency_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "requests": {
      "items": {
        "$ref": "#/$defs/BatchGenerateItem"
      },
      "maxItems": 20,
      "minItems": 1,
      "title": "Requests",
      "type": "array"
    },
    "platform": {
      "default": "tiktok",
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "linkedin"
      ],
      "title": "Platform",
      "type": "string"
    },
    "mode": {
      "anyOf": [
        {
          "enum": [
            "instant",
            "template",
            "off",
            "quick",
            "smart",
            "llm",
            "on",
            "fast",
            "research",
            "search",
            "deep",
            "deep_research",
            "auto"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Mode"
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "maxLength": 40,
            "minLength": 1,
            "pattern": "^[a-z0-9_-]+$",
            "type": "string"
          },
          "maxItems": 5,
          "minItems": 1,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tags"
    },
    "verbosity": {
      "default": "standard",
      "enum": [
        "minimal",
        "standard",
        "full"
      ],
      "title": "Verbosity",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "requests"
  ],
  "$defs": {
    "BatchGenerateItem": {
      "additionalProperties": false,
      "description": "One item in a generate_hooks_batch call; mirrors the REST batch item schema.\n\nA typed pydantic model (WP-C.4) so tools/list inputSchema shows the item shape\n(topic/count/archetypes/style) instead of a bare additionalProperties:true.\nextra=\"forbid\" so an unknown key (e.g. a per-item `mode`, which is set once at the\nbatch level) is a typed invalid_request at the argument-validation boundary rather\nthan being silently dropped and billed at the batch mode.",
      "properties": {
        "topic": {
          "maxLength": 200,
          "minLength": 3,
          "title": "Topic",
          "type": "string"
        },
        "count": {
          "default": 10,
          "maximum": 25,
          "minimum": 1,
          "title": "Count",
          "type": "integer"
        },
        "archetypes": {
          "anyOf": [
            {
              "items": {
                "enum": [
                  "curiosity_gap",
                  "contrarian",
                  "data_shock",
                  "story",
                  "transformation",
                  "listicle",
                  "authority",
                  "urgency"
                ],
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Archetypes"
        },
        "style": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Style"
        }
      },
      "required": [
        "topic"
      ],
      "title": "BatchGenerateItem",
      "type": "object"
    }
  },
  "title": "generate_hooks_batchArguments"
}

score_hook

Score any hook text on 5 dimensions with rewrite tips. 1 credit. Deterministic heuristic scorer (no LLM). Args: text (3-300), platform, tags (1-5 fleet slugs, WP-J), verbosity (full keeps per-dimension attribution), api_key, idempotency_key (replay not re-charged). Returns {score:{...,total}, verdict, suggestions, confidence, disclaimer, credits_charged, credits_remaining, request_id}. Errors: unauthorized, invalid_request, insufficient_credits, rate_limited.

Parameters6

text	string	required
platform	string	optional
tags	any	optional
verbosity	string	optional
api_key	any	optional
idempotency_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "maxLength": 300,
      "minLength": 3,
      "title": "Text",
      "type": "string"
    },
    "platform": {
      "default": "tiktok",
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "linkedin"
      ],
      "title": "Platform",
      "type": "string"
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "maxLength": 40,
            "minLength": 1,
            "pattern": "^[a-z0-9_-]+$",
            "type": "string"
          },
          "maxItems": 5,
          "minItems": 1,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tags"
    },
    "verbosity": {
      "default": "standard",
      "enum": [
        "minimal",
        "standard",
        "full"
      ],
      "title": "Verbosity",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "text"
  ],
  "title": "score_hookArguments"
}

score_hooks_batch

Score many hooks at once; get them ranked plus the `best`. 1 credit each. All-or-nothing charge. Args: texts (1-25, each 3-300), platform, tags (1-5 fleet slugs, WP-J), verbosity (applies to every result), api_key, idempotency_key. Returns {results:[{text, score, verdict, rank}], best, credits_charged, credits_remaining, request_id}. Errors: unauthorized, invalid_request, insufficient_credits, rate_limited.

Parameters6

texts	array	required
platform	string	optional
tags	any	optional
verbosity	string	optional
api_key	any	optional
idempotency_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "texts": {
      "items": {
        "maxLength": 300,
        "minLength": 3,
        "type": "string"
      },
      "maxItems": 25,
      "minItems": 1,
      "title": "Texts",
      "type": "array"
    },
    "platform": {
      "default": "tiktok",
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "linkedin"
      ],
      "title": "Platform",
      "type": "string"
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "maxLength": 40,
            "minLength": 1,
            "pattern": "^[a-z0-9_-]+$",
            "type": "string"
          },
          "maxItems": 5,
          "minItems": 1,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tags"
    },
    "verbosity": {
      "default": "standard",
      "enum": [
        "minimal",
        "standard",
        "full"
      ],
      "title": "Verbosity",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "texts"
  ],
  "title": "score_hooks_batchArguments"
}

remix_hook

Rewrite an existing hook into a target archetype. 2 credits per variant. Deterministic per input. Args: text (3-300), target_archetype (an id; see list_archetypes), count (1-5), tags (1-5 fleet slugs, WP-J), verbosity, api_key, idempotency_key. Billed only for variants returned. Returns {original:{text, score}, remixes:[{id, text, archetype, score, rank}], topic_core, reason, score_disclaimer, credits_charged, credits_remaining, request_id}. Errors: unauthorized, invalid_request, insufficient_credits, rate_limited.

Parameters7

text	string	required
target_archetype	string	required
count	integer	optional
tags	any	optional
verbosity	string	optional
api_key	any	optional
idempotency_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "maxLength": 300,
      "minLength": 3,
      "title": "Text",
      "type": "string"
    },
    "target_archetype": {
      "enum": [
        "curiosity_gap",
        "contrarian",
        "data_shock",
        "story",
        "transformation",
        "listicle",
        "authority",
        "urgency"
      ],
      "title": "Target Archetype",
      "type": "string"
    },
    "count": {
      "default": 1,
      "maximum": 5,
      "minimum": 1,
      "title": "Count",
      "type": "integer"
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "maxLength": 40,
            "minLength": 1,
            "pattern": "^[a-z0-9_-]+$",
            "type": "string"
          },
          "maxItems": 5,
          "minItems": 1,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tags"
    },
    "verbosity": {
      "default": "standard",
      "enum": [
        "minimal",
        "standard",
        "full"
      ],
      "title": "Verbosity",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "text",
    "target_archetype"
  ],
  "title": "remix_hookArguments"
}

list_hooks

List the hooks this account has bought, newest first. Free (WP-G). Persisted hooks stay retrievable for 90 days. Args: mode (instant|smart|research| remix), since (ISO timestamp), tag (exact fleet-tag match, WP-SCOPE), topic (case-insensitive substring, WP-SCOPE), limit (1-100, default 20), offset (>=0), api_key. Returns {hooks:[{hook_id, text, archetype, mode, score_total, created_at, request_id}], limit, offset, total}. Errors: unauthorized, rate_limited.

Parameters7

mode	any	optional
since	any	optional
tag	any	optional
topic	any	optional
limit	integer	optional
offset	integer	optional
api_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "mode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Mode"
    },
    "since": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Since"
    },
    "tag": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tag"
    },
    "topic": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Topic"
    },
    "limit": {
      "default": 20,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "title": "Offset",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "list_hooksArguments"
}

get_hook

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, score_total, score, prompt_version, request_id, created_at, outcomes:[...], outcome_summary:{count, max_views, avg_views}}. Report results with report_outcome. Errors: unauthorized, not_found, rate_limited.

Parameters2

hook_id	string	required
api_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "hook_id": {
      "title": "Hook Id",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "hook_id"
  ],
  "title": "get_hookArguments"
}

list_outcomes

List the posted outcomes THIS account has reported, newest first. Free (WP-LIFE). Retrieve your own submitted telemetry in bulk (per-hook it rides get_hook). Args: platform (tiktok|instagram|youtube|x|other), since (ISO timestamp), hook_id (one hook), limit (1-200, default 50), offset (>=0), api_key. Each row carries the outcome plus its snapshot (hook_text, topic, mode, archetype, claim_type, score_total, score_source, prompt_version, tags). Returns {outcomes:[...], limit, offset, total}. Errors: unauthorized, invalid_request, rate_limited.

Parameters6

platform	any	optional
since	any	optional
hook_id	any	optional
limit	integer	optional
offset	integer	optional
api_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "platform": {
      "anyOf": [
        {
          "enum": [
            "tiktok",
            "instagram",
            "youtube",
            "x",
            "other"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Platform"
    },
    "since": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Since"
    },
    "hook_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Hook Id"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "title": "Offset",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "list_outcomesArguments"
}

report_outcome

Report what a bought hook actually did once posted. FREE (WP-H). Honest telemetry feeding the outcome corpus (no view prediction claimed). Args: hook_id, platform (tiktok|instagram|youtube|x|other), posted_at (ISO, not >48h future), views/likes (0..1e11), retention_pct? (0-100), url? (http(s)+host), api_key, idempotency_key. Caps 20/hook, 500/day; an exact duplicate is a conflict. Returns {outcome, aggregate, reward_credits, credits_remaining?}. Errors: unauthorized, not_found, invalid_request, conflict, rate_limited.

Parameters9

hook_id	string	required
platform	string	required
posted_at	string	required
views	integer	required
likes	any	optional
retention_pct	any	optional
url	any	optional
api_key	any	optional
idempotency_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "hook_id": {
      "title": "Hook Id",
      "type": "string"
    },
    "platform": {
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "other"
      ],
      "title": "Platform",
      "type": "string"
    },
    "posted_at": {
      "title": "Posted At",
      "type": "string"
    },
    "views": {
      "minimum": 0,
      "title": "Views",
      "type": "integer"
    },
    "likes": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Likes"
    },
    "retention_pct": {
      "anyOf": [
        {
          "maximum": 100,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Retention Pct"
    },
    "url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Url"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "hook_id",
    "platform",
    "posted_at",
    "views"
  ],
  "title": "report_outcomeArguments"
}

start_generate_job

Submit a generate as an async job; poll get_job for the result. Same args as generate_hooks (tags persist); charge runs on the worker; results are always full-verbosity; prefer for research. EITHER topic OR topics (1-20 subjects, ONE job + one atomic charge, result = the batch envelope); both or neither = invalid_request. Returns {job_id, status, estimated_seconds, poll_after_seconds, status_url, expires_at, requeued}. Errors: unauthorized, invalid_request, insufficient_credits, idempotency_conflict, rate_limited.

Parameters10

topic	any	optional
topics	any	optional
platform	string	optional
count	integer	optional
archetypes	any	optional
style	any	optional
mode	any	optional
tags	any	optional
api_key	any	optional
idempotency_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "topic": {
      "anyOf": [
        {
          "maxLength": 200,
          "minLength": 3,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Topic"
    },
    "topics": {
      "anyOf": [
        {
          "items": {
            "maxLength": 200,
            "minLength": 3,
            "type": "string"
          },
          "maxItems": 20,
          "minItems": 1,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Topics"
    },
    "platform": {
      "default": "tiktok",
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "linkedin"
      ],
      "title": "Platform",
      "type": "string"
    },
    "count": {
      "default": 10,
      "maximum": 25,
      "minimum": 1,
      "title": "Count",
      "type": "integer"
    },
    "archetypes": {
      "anyOf": [
        {
          "items": {
            "enum": [
              "curiosity_gap",
              "contrarian",
              "data_shock",
              "story",
              "transformation",
              "listicle",
              "authority",
              "urgency"
            ],
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Archetypes"
    },
    "style": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Style"
    },
    "mode": {
      "anyOf": [
        {
          "enum": [
            "instant",
            "template",
            "off",
            "quick",
            "smart",
            "llm",
            "on",
            "fast",
            "research",
            "search",
            "deep",
            "deep_research",
            "auto"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Mode"
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "maxLength": 40,
            "minLength": 1,
            "pattern": "^[a-z0-9_-]+$",
            "type": "string"
          },
          "maxItems": 5,
          "minItems": 1,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tags"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "title": "start_generate_jobArguments"
}

get_job

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 existence leak). Returns {job_id, status, stage, progress_pct, eta_seconds, elapsed_ms, poll_after_seconds, result, error}. Errors: unauthorized, not_found, rate_limited.

Parameters2

job_id	string	required
api_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "get_jobArguments"
}

list_jobs

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.

Parameters3

limit	integer	optional
offset	integer	optional
api_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "title": "Offset",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "list_jobsArguments"
}

list_webhook_deliveries

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), offset (>=0), api_key. Each row has {delivery_id, event_type, status, attempts, last_status_code, error, timestamps, next_attempt_at, payload_preview (200 chars; the full body is never returned)}. Dead rows are kept 7 days. Errors: unauthorized, invalid_request, rate_limited.

Parameters4

status	any	optional
limit	integer	optional
offset	integer	optional
api_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "title": "Offset",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "list_webhook_deliveriesArguments"
}

redrive_webhook_delivery

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 dies again, dead-letters normally. Args: delivery_id (from list_webhook_deliveries), api_key. Returns the refreshed row. Errors: unauthorized, forbidden, not_found, conflict, rate_limited.

Parameters2

delivery_id	string	required
api_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "delivery_id": {
      "title": "Delivery Id",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "required": [
    "delivery_id"
  ],
  "title": "redrive_webhook_deliveryArguments"
}

get_activity

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 SSE feed at GET /v1/activity/stream. Args: recent_limit (1-100, default 20), api_key. Errors: unauthorized, rate_limited.

Parameters2

recent_limit	integer	optional
api_key	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "recent_limit": {
      "default": 20,
      "title": "Recent Limit",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key"
    }
  },
  "title": "get_activityArguments"
}

VHGENGINE

app.railway.up.engine-production-3bdc/vhgengine (MCP)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

signup

getting_started

list_archetypes

pricing

get_estimates

health

get_account

get_usage

add_credits

create_checkout

create_key

list_keys

revoke_key

delete_account

generate_hooks

generate_hooks_batch

score_hook

score_hooks_batch

remix_hook

list_hooks

get_hook

list_outcomes

report_outcome

start_generate_job

get_job

list_jobs

list_webhook_deliveries

redrive_webhook_delivery

get_activity

Install

Remote endpoint