VHGENGINE

Officialdeprecated38 tools

by engine-production-3bdc

Agents-first viral-hook engine: generate, score, and remix short-form hooks over MCP.

MCP Server: app.railway.up.engine-production-3bdc/vhgengine

This MCP server, app.railway.up.engine-production-3bdc/vhgengine, provides an agents-first workflow for generating, scoring, and remixing short-form hooks via MCP. The server description indicates it focuses on producing short-form hook variations and evaluating and reworking them.

🛠️ Key Features

Generate short-form hooks
Score hooks
Remix/rework hooks
Agents-first approach

🚀 Use Cases

Producing multiple short-form hook options for iterative selection
Evaluating hook outputs and refining them through remixing
Supporting agent-driven content variations over MCP

⚡ Developer Benefits

Accessible through MCP tools (38 total tools)
Supports a generate → score → remix loop for short-form hooks

⚠️ Limitations

Limited description is available: no details on specific tools’ inputs/outputs, auth, or deployment behavior

Captured live from the server via tools/list.

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. An idempotent replay returns the SAME account with replayed:true and a NULL api_key (the plaintext is never stored), so branch on `replayed`, never on the empty key. Cost: free. Errors: invalid_request, idempotency_conflict, rate_limited.

Parameters3

name	string	optional	Display name for the account, 1-100 chars. Purely a label (it is never checked for uniqueness); defaults to 'agent'.
email	any	optional	OPTIONAL contact address. Never required, never verified, and never used to authenticate; the api_key is the only credential.
idempotency_key	any	optional	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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "default": "agent",
      "description": "Display name for the account, 1-100 chars. Purely a label (it is never checked for uniqueness); defaults to 'agent'.",
      "title": "Name",
      "type": "string"
    },
    "email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "OPTIONAL contact address. Never required, never verified, and never used to authenticate; the api_key is the only credential.",
      "title": "Email"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.",
      "title": "Idempotency Key"
    }
  },
  "title": "signupArguments",
  "additionalProperties": false
}

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",
  "additionalProperties": false
}

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",
  "additionalProperties": false
}

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",
  "additionalProperties": false
}

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",
  "additionalProperties": false
}

health

Deep health: DB read+write probe, worker/queue, backup + integrity. Free. Same db.write_probe/backup.status/backup.offsite_status/integrity.status calls GET /health makes, so the two can never disagree. status is "ok" only when the DB both reads AND writes. Returns {status, version, time, llm_configured, outcomes_reported_total, job_worker_alive, job_queue_depth, last_backup_at, backup_count, offsite, integrity}. llm_configured never calls an LLM; CHECK job_worker_alive before start_generate_job (false: a queued job never runs).

Parameters

No parameters.

Raw schema

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

get_account

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 ceiling by taking a rate_limited mid-run; this read itself consumes one of those calls. No API key is ever echoed back. Errors: unauthorized, rate_limited.

Parameters1

api_key

any

optional

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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "get_accountArguments",
  "additionalProperties": false
}

get_usage

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_operation}, recent:[...]} (each row carries key_prefix; tags in metadata). Errors: unauthorized, invalid_request, rate_limited.

Parameters6

recent_limit	integer	optional	Max recent ledger rows to return, 1-200. Totals are unaffected by this; it only sizes `recent`.
offset	integer	optional	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 past the end is an empty `recent`, never an error. `totals` always covers all history and is never paged away. For the WHOLE ledger in one call use export_usage instead.
request_id	any	optional	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 charged nothing matches no rows and comes back as an empty `recent`, not an error. Omit for all recent charges.
tag	any	optional	Filter to rows carrying EXACTLY this fleet tag (exact match, not a substring). Omit for every tag.
key_prefix	any	optional	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	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "recent_limit": {
      "default": 50,
      "description": "Max recent ledger rows to return, 1-200. Totals are unaffected by this; it only sizes `recent`.",
      "maximum": 200,
      "minimum": 1,
      "title": "Recent Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "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 past the end is an empty `recent`, never an error. `totals` always covers all history and is never paged away. For the WHOLE ledger in one call use export_usage instead.",
      "maximum": 9223372036854776000,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    },
    "request_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 charged nothing matches no rows and comes back as an empty `recent`, not an error. Omit for all recent charges.",
      "title": "Request Id"
    },
    "tag": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Filter to rows carrying EXACTLY this fleet tag (exact match, not a substring). Omit for every tag.",
      "title": "Tag"
    },
    "key_prefix": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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.",
      "title": "Key Prefix"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "get_usageArguments",
  "additionalProperties": false
}

export_usage

Export EVERYTHING this account owns in ONE body: ledger, hooks, outcomes. Free. The take-it-with-you call; make it BEFORE delete_account. Same body as GET /v1/usage/export?format=json (csv is a download shape with no MCP carrier and its columns are a subset of `events`). UNBOUNDED, no paging: on a big account prefer get_usage / list_hooks / list_outcomes. `email` is masked without the admin scope. Returns {account_id, email, count, events, hooks, outcomes}; tag/key_prefix narrow events. Errors: unauthorized, forbidden (key lacks the read scope), rate_limited.

Parameters3

tag	any	optional	Filter to rows carrying EXACTLY this fleet tag (exact match, not a substring). Omit for every tag.
key_prefix	any	optional	Narrow the LEDGER to charges made with ONE api key, identified by the 12-char prefix from list_keys. `hooks` and `outcomes` are always the full set and are NOT narrowed by this. Omit for every key.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "tag": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Filter to rows carrying EXACTLY this fleet tag (exact match, not a substring). Omit for every tag.",
      "title": "Tag"
    },
    "key_prefix": {
      "anyOf": [
        {
          "maxLength": 64,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Narrow the LEDGER to charges made with ONE api key, identified by the 12-char prefix from list_keys. `hooks` and `outcomes` are always the full set and are NOT narrowed by this. Omit for every key.",
      "title": "Key Prefix",
      "maxLength": 64
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "export_usageArguments",
  "additionalProperties": false
}

list_runs

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 true, never on a short page. Same composed read GET /v1/runs makes, so the two can never disagree. Errors: unauthorized, invalid_request, rate_limited.

Parameters7

request_id	any	optional	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 have.
operation	any	optional	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 empty page, never an error.
charged_only	boolean	optional	true (default): only calls that COST credits. false: also include grants and zero-cost calls.
limit	integer	optional	Max runs to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation.
offset	integer	optional	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. The ceiling is SQLite's largest bindable integer: above it the read could only ever have been a 500, so it is a typed invalid_request instead.
cursor	integer	optional	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 your whole history in bounded reads.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "anyOf": [
        {
          "maxLength": 64,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 have.",
      "title": "Request Id",
      "maxLength": 64
    },
    "operation": {
      "anyOf": [
        {
          "maxLength": 64,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 empty page, never an error.",
      "title": "Operation",
      "maxLength": 64
    },
    "charged_only": {
      "default": true,
      "description": "true (default): only calls that COST credits. false: also include grants and zero-cost calls.",
      "title": "Charged Only",
      "type": "boolean"
    },
    "limit": {
      "default": 50,
      "description": "Max runs to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation.",
      "maximum": 200,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "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. The ceiling is SQLite's largest bindable integer: above it the read could only ever have been a 500, so it is a typed invalid_request instead.",
      "maximum": 9223372036854776000,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    },
    "cursor": {
      "default": 0,
      "description": "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 your whole history in bounded reads.",
      "maximum": 9223372036854774000,
      "minimum": 0,
      "title": "Cursor",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "list_runsArguments",
  "additionalProperties": false
}

quote

Price and time a generate BEFORE you commit to it, without spending. Free. Answers what you cannot otherwise learn without paying: which engine will BILL (mode=auto resolves here), credits_max, expected_wait, and whether this key can afford it now (balance AND any daily account/key cap, spelled out in `blocker`). Same validation as generate_hooks, so a bad topic/archetype/mode fails HERE. credits_max is a CEILING (you pay per hook RETURNED) and nothing is reserved. Errors: unauthorized, invalid_request, rate_limited.

Parameters6

topic	string	required	The topic you intend to generate for, 3-200 chars. It is fully VALIDATED here, so a bad topic is an invalid_request now instead of after you commit to spending.
platform	string	optional	Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted.
count	integer	optional	How many hooks you intend to ask for, 1-25. Drives the quoted ceiling: credits_max = base + per_hook * count.
archetypes	any	optional	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 deliberately narrowing a deck.
mode	enum	optional	Generation engine and therefore the price: instant (0 base + 1/hook, deterministic templates, sub-second), smart (0 + 2/hook, one LLM call, seconds), research (10 + 4/hook, brief->draft->judge, tens of seconds). Aliases: template\|off\|quick->instant, llm\|on\|fast->smart, search\|deep\|deep_research->research. Omit (or auto) -> smart when an LLM key is configured, else instant.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "topic": {
      "description": "The topic you intend to generate for, 3-200 chars. It is fully VALIDATED here, so a bad topic is an invalid_request now instead of after you commit to spending.",
      "maxLength": 200,
      "minLength": 3,
      "title": "Topic",
      "type": "string"
    },
    "platform": {
      "default": "tiktok",
      "description": "Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted.",
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "linkedin"
      ],
      "title": "Platform",
      "type": "string"
    },
    "count": {
      "default": 10,
      "description": "How many hooks you intend to ask for, 1-25. Drives the quoted ceiling: credits_max = base + per_hook * count.",
      "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,
      "description": "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 deliberately narrowing a deck.",
      "title": "Archetypes",
      "items": {
        "enum": [
          "curiosity_gap",
          "contrarian",
          "data_shock",
          "story",
          "transformation",
          "listicle",
          "authority",
          "urgency"
        ],
        "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,
      "description": "Generation engine and therefore the price: instant (0 base + 1/hook, deterministic templates, sub-second), smart (0 + 2/hook, one LLM call, seconds), research (10 + 4/hook, brief->draft->judge, tens of seconds). Aliases: template|off|quick->instant, llm|on|fast->smart, search|deep|deep_research->research. Omit (or auto) -> smart when an LLM key is configured, else instant.",
      "title": "Mode",
      "enum": [
        "instant",
        "template",
        "off",
        "quick",
        "smart",
        "llm",
        "on",
        "fast",
        "research",
        "search",
        "deep",
        "deep_research",
        "auto",
        null
      ]
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "required": [
    "topic"
  ],
  "title": "quoteArguments",
  "additionalProperties": false
}

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	Credits to add, 1-10000. Charged operations spend these; see pricing for the per-mode cost. The grant also has a per-account balance ceiling, so a large top-up on a full balance is invalid_request.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.
idempotency_key	any	optional	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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.
admin_key	any	optional	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 configured is unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "amount": {
      "description": "Credits to add, 1-10000. Charged operations spend these; see pricing for the per-mode cost. The grant also has a per-account balance ceiling, so a large top-up on a full balance is invalid_request.",
      "maximum": 10000,
      "minimum": 1,
      "title": "Amount",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.",
      "title": "Idempotency Key"
    },
    "admin_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 configured is unauthorized.",
      "title": "Admin Key"
    }
  },
  "required": [
    "amount"
  ],
  "title": "add_creditsArguments",
  "additionalProperties": false
}

list_billing_events

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.

Parameters3

limit	integer	optional	Max billing events to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation.
offset	integer	optional	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. The ceiling is SQLite's largest bindable integer: above it the read could only ever have been a 500, so it is a typed invalid_request instead.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 50,
      "description": "Max billing events to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation.",
      "maximum": 200,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "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. The ceiling is SQLite's largest bindable integer: above it the read could only ever have been a 500, so it is a typed invalid_request instead.",
      "maximum": 9223372036854776000,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "list_billing_eventsArguments",
  "additionalProperties": false
}

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	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 not an offered pack is invalid_request.
success_url	any	optional	Where Stripe sends the browser after a successful payment. At most 2048 characters. Omit to use the deployment's default landing page.
cancel_url	any	optional	Where Stripe sends the browser if your human abandons checkout. At most 2048 characters. Omit to use the deployment's default.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "pack": {
      "description": "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 not an offered pack is invalid_request.",
      "minimum": 1,
      "title": "Pack",
      "type": "integer"
    },
    "success_url": {
      "anyOf": [
        {
          "maxLength": 2048,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Where Stripe sends the browser after a successful payment. At most 2048 characters. Omit to use the deployment's default landing page.",
      "title": "Success Url",
      "maxLength": 2048
    },
    "cancel_url": {
      "anyOf": [
        {
          "maxLength": 2048,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Where Stripe sends the browser if your human abandons checkout. At most 2048 characters. Omit to use the deployment's default.",
      "title": "Cancel Url",
      "maxLength": 2048
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "required": [
    "pack"
  ],
  "title": "create_checkoutArguments",
  "additionalProperties": false
}

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	Label for the new key, 1-100 chars, shown by list_keys so you can tell delegated keys apart. Defaults to 'key'.
scopes	any	optional	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 subset to hand a sub-agent strictly less power than you hold.
daily_credit_cap	any	optional	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 reports spent_today against this.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "default": "key",
      "description": "Label for the new key, 1-100 chars, shown by list_keys so you can tell delegated keys apart. Defaults to 'key'.",
      "maxLength": 100,
      "minLength": 1,
      "title": "Name",
      "type": "string"
    },
    "scopes": {
      "anyOf": [
        {
          "items": {
            "enum": [
              "read",
              "spend",
              "admin"
            ],
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 subset to hand a sub-agent strictly less power than you hold.",
      "title": "Scopes",
      "items": {
        "enum": [
          "read",
          "spend",
          "admin"
        ],
        "type": "string"
      }
    },
    "daily_credit_cap": {
      "anyOf": [
        {
          "maximum": 100000,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 reports spent_today against this.",
      "title": "Daily Credit Cap",
      "minimum": 1,
      "maximum": 100000
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "create_keyArguments",
  "additionalProperties": false
}

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,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "list_keysArguments",
  "additionalProperties": false
}

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	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	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "prefix": {
      "description": "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.",
      "title": "Prefix",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "required": [
    "prefix"
  ],
  "title": "revoke_keyArguments",
  "additionalProperties": false
}

delete_account

Permanently delete this account. TERMINAL, not reversible. Admin scope (WP-LIFE). Pass confirm="delete" (guards an accidental call). Revokes ALL your keys, deletes your hooks, webhook, deliveries, jobs and idempotency rows, KEEPS the immutable financial ledger, and ANONYMIZES your outcomes into the shared corpus. Take what you still want FIRST: export_usage returns the ledger, every hook and every outcome in ONE call (get_usage / list_hooks / list_outcomes are the paged alternative). Errors: unauthorized, forbidden, invalid_request, rate_limited.

Parameters2

confirm	string	required	Must be exactly the string "delete". A guard: any other value (or omitting it) fails argument validation before anything is touched, so an accidental invocation cannot destroy the account.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "confirm": {
      "const": "delete",
      "description": "Must be exactly the string \"delete\". A guard: any other value (or omitting it) fails argument validation before anything is touched, so an accidental invocation cannot destroy the account.",
      "title": "Confirm",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "required": [
    "confirm"
  ],
  "title": "delete_accountArguments",
  "additionalProperties": false
}

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 never bills a broke account. Deterministic only in instant; a progressToken streams stages; the hook id is `hooks[].id`. CANCELLING DOES NOT REFUND: a timeout cannot stop the engine thread, so the call still charges and persists. Send idempotency_key, or recover via list_hooks. Errors: unauthorized, invalid_request, llm_unavailable, insufficient_credits.

Parameters11

topic	string	required	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 brief is researched against.
platform	string	optional	Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted.
count	integer	optional	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 expensive combination.
archetypes	any	optional	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 deliberately narrowing a deck.
style	any	optional	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, so it cannot change the voice there. Omit for the engine's default register.
mode	enum	optional	Generation engine and therefore the price: instant (0 base + 1/hook, deterministic templates, sub-second), smart (0 + 2/hook, one LLM call, seconds), research (10 + 4/hook, brief->draft->judge, tens of seconds). Aliases: template\|off\|quick->instant, llm\|on\|fast->smart, search\|deep\|deep_research->research. Omit (or auto) -> smart when an LLM key is configured, else instant.
tags	any	optional	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 later with get_usage(tag=...) / list_hooks(tag=...).
verbosity	string	optional	How much of the response envelope to return: minimal (ids/text/totals only), standard (the default), full (adds per-dimension score attribution and timings). Shapes the RESPONSE only, never what is generated, persisted, hashed for idempotency, or charged.
deadline_ms	any	optional	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 get_job instead of generating inline. Omit to always block until the hooks are ready.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.
idempotency_key	any	optional	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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.

Raw schema

{
  "type": "object",
  "properties": {
    "topic": {
      "description": "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 brief is researched against.",
      "maxLength": 200,
      "minLength": 3,
      "title": "Topic",
      "type": "string"
    },
    "platform": {
      "default": "tiktok",
      "description": "Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted.",
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "linkedin"
      ],
      "title": "Platform",
      "type": "string"
    },
    "count": {
      "default": 10,
      "description": "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 expensive combination.",
      "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,
      "description": "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 deliberately narrowing a deck.",
      "title": "Archetypes",
      "items": {
        "enum": [
          "curiosity_gap",
          "contrarian",
          "data_shock",
          "story",
          "transformation",
          "listicle",
          "authority",
          "urgency"
        ],
        "type": "string"
      }
    },
    "style": {
      "anyOf": [
        {
          "description": "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, so it cannot change the voice there. Omit for the engine's default register.",
          "maxLength": 200,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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, so it cannot change the voice there. Omit for the engine's default register.",
      "title": "Style",
      "maxLength": 200
    },
    "mode": {
      "anyOf": [
        {
          "enum": [
            "instant",
            "template",
            "off",
            "quick",
            "smart",
            "llm",
            "on",
            "fast",
            "research",
            "search",
            "deep",
            "deep_research",
            "auto"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Generation engine and therefore the price: instant (0 base + 1/hook, deterministic templates, sub-second), smart (0 + 2/hook, one LLM call, seconds), research (10 + 4/hook, brief->draft->judge, tens of seconds). Aliases: template|off|quick->instant, llm|on|fast->smart, search|deep|deep_research->research. Omit (or auto) -> smart when an LLM key is configured, else instant.",
      "title": "Mode",
      "enum": [
        "instant",
        "template",
        "off",
        "quick",
        "smart",
        "llm",
        "on",
        "fast",
        "research",
        "search",
        "deep",
        "deep_research",
        "auto",
        null
      ]
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "maxLength": 40,
            "minLength": 1,
            "pattern": "^[a-z0-9_-]+$",
            "type": "string"
          },
          "maxItems": 5,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 later with get_usage(tag=...) / list_hooks(tag=...).",
      "title": "Tags",
      "maxItems": 5,
      "items": {
        "maxLength": 40,
        "minLength": 1,
        "pattern": "^[a-z0-9_-]+$",
        "type": "string"
      }
    },
    "verbosity": {
      "default": "standard",
      "description": "How much of the response envelope to return: minimal (ids/text/totals only), standard (the default), full (adds per-dimension score attribution and timings). Shapes the RESPONSE only, never what is generated, persisted, hashed for idempotency, or charged.",
      "enum": [
        "minimal",
        "standard",
        "full"
      ],
      "title": "Verbosity",
      "type": "string"
    },
    "deadline_ms": {
      "anyOf": [
        {
          "maximum": 600000,
          "minimum": 1000,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 get_job instead of generating inline. Omit to always block until the hooks are ready.",
      "title": "Deadline Ms",
      "minimum": 1000,
      "maximum": 600000
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.",
      "title": "Idempotency Key"
    }
  },
  "required": [
    "topic"
  ],
  "title": "generate_hooksArguments",
  "additionalProperties": false
}

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; a progressToken streams item i/n; hook ids are results[i].hooks[j].id. CANCELLING DOES NOT REFUND: a timeout cannot stop the engine thread, so the batch still charges and persists. Send idempotency_key. Errors: unauthorized, invalid_request, llm_unavailable, insufficient_credits.

Parameters7

requests	array	required	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. Unknown item keys are invalid_request.
platform	string	optional	Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted.
mode	enum	optional	Generation engine and therefore the price: instant (0 base + 1/hook, deterministic templates, sub-second), smart (0 + 2/hook, one LLM call, seconds), research (10 + 4/hook, brief->draft->judge, tens of seconds). Aliases: template\|off\|quick->instant, llm\|on\|fast->smart, search\|deep\|deep_research->research. Omit (or auto) -> smart when an LLM key is configured, else instant.
tags	any	optional	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 later with get_usage(tag=...) / list_hooks(tag=...).
verbosity	string	optional	How much of the response envelope to return: minimal (ids/text/totals only), standard (the default), full (adds per-dimension score attribution and timings). Shapes the RESPONSE only, never what is generated, persisted, hashed for idempotency, or charged.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.
idempotency_key	any	optional	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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.

Raw schema

{
  "type": "object",
  "properties": {
    "requests": {
      "description": "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. Unknown item keys are invalid_request.",
      "items": {
        "$ref": "#/$defs/BatchGenerateItem"
      },
      "maxItems": 20,
      "minItems": 1,
      "title": "Requests",
      "type": "array"
    },
    "platform": {
      "default": "tiktok",
      "description": "Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted.",
      "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,
      "description": "Generation engine and therefore the price: instant (0 base + 1/hook, deterministic templates, sub-second), smart (0 + 2/hook, one LLM call, seconds), research (10 + 4/hook, brief->draft->judge, tens of seconds). Aliases: template|off|quick->instant, llm|on|fast->smart, search|deep|deep_research->research. Omit (or auto) -> smart when an LLM key is configured, else instant.",
      "title": "Mode",
      "enum": [
        "instant",
        "template",
        "off",
        "quick",
        "smart",
        "llm",
        "on",
        "fast",
        "research",
        "search",
        "deep",
        "deep_research",
        "auto",
        null
      ]
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "maxLength": 40,
            "minLength": 1,
            "pattern": "^[a-z0-9_-]+$",
            "type": "string"
          },
          "maxItems": 5,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 later with get_usage(tag=...) / list_hooks(tag=...).",
      "title": "Tags",
      "maxItems": 5,
      "items": {
        "maxLength": 40,
        "minLength": 1,
        "pattern": "^[a-z0-9_-]+$",
        "type": "string"
      }
    },
    "verbosity": {
      "default": "standard",
      "description": "How much of the response envelope to return: minimal (ids/text/totals only), standard (the default), full (adds per-dimension score attribution and timings). Shapes the RESPONSE only, never what is generated, persisted, hashed for idempotency, or charged.",
      "enum": [
        "minimal",
        "standard",
        "full"
      ],
      "title": "Verbosity",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.",
      "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": {
          "description": "What this item's hooks are about, 3-200 chars. Required: there is no batch-level topic.",
          "maxLength": 200,
          "minLength": 3,
          "title": "Topic",
          "type": "string"
        },
        "count": {
          "default": 10,
          "description": "Hooks for THIS item, 1-25 (default 10). Each item is priced separately at base + per_hook * hooks_returned.",
          "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,
          "description": "Restrict THIS item to these archetype ids (see list_archetypes); omit to let the engine spread. Per item, not batch-wide.",
          "title": "Archetypes",
          "items": {
            "enum": [
              "curiosity_gap",
              "contrarian",
              "data_shock",
              "story",
              "transformation",
              "listicle",
              "authority",
              "urgency"
            ],
            "type": "string"
          }
        },
        "style": {
          "anyOf": [
            {
              "maxLength": 200,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "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, so it cannot change the voice there. Omit for the engine's default register.",
          "title": "Style",
          "maxLength": 200
        }
      },
      "required": [
        "topic"
      ],
      "title": "BatchGenerateItem",
      "type": "object"
    }
  },
  "title": "generate_hooks_batchArguments",
  "additionalProperties": false
}

score_hook

Score any hook text on 5 dimensions with rewrite tips. 1 credit. 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 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.

Parameters7

text	string	required	The hook line to score, 3-300 chars. Any text is accepted (it does not have to be one VHGENGINE generated) and it is never persisted as a hook you own.
platform	string	optional	Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted.
topic	any	optional	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 hook: the scorer's verbatim-echo penalty only fires when it is told the topic, so a hook that repeats its own subject scores up to 8 points higher without it. Omit to score the text on its own (unchanged behaviour). Two caveats on exactness: a hook flagged contains_placeholder_stat was scored with a fabricated-number penalty this cannot apply, and a total capped at the deterministic template ceiling says so in score.notes at verbosity=full.
tags	any	optional	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 later with get_usage(tag=...) / list_hooks(tag=...).
verbosity	string	optional	How much of the response envelope to return: minimal (ids/text/totals only), standard (the default), full (adds per-dimension score attribution and timings). Shapes the RESPONSE only, never what is generated, persisted, hashed for idempotency, or charged.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.
idempotency_key	any	optional	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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "description": "The hook line to score, 3-300 chars. Any text is accepted (it does not have to be one VHGENGINE generated) and it is never persisted as a hook you own.",
      "maxLength": 300,
      "minLength": 3,
      "title": "Text",
      "type": "string"
    },
    "platform": {
      "default": "tiktok",
      "description": "Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted.",
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "linkedin"
      ],
      "title": "Platform",
      "type": "string"
    },
    "topic": {
      "anyOf": [
        {
          "maxLength": 200,
          "minLength": 3,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 hook: the scorer's verbatim-echo penalty only fires when it is told the topic, so a hook that repeats its own subject scores up to 8 points higher without it. Omit to score the text on its own (unchanged behaviour). Two caveats on exactness: a hook flagged contains_placeholder_stat was scored with a fabricated-number penalty this cannot apply, and a total capped at the deterministic template ceiling says so in score.notes at verbosity=full.",
      "title": "Topic",
      "minLength": 3,
      "maxLength": 200
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "maxLength": 40,
            "minLength": 1,
            "pattern": "^[a-z0-9_-]+$",
            "type": "string"
          },
          "maxItems": 5,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 later with get_usage(tag=...) / list_hooks(tag=...).",
      "title": "Tags",
      "maxItems": 5,
      "items": {
        "maxLength": 40,
        "minLength": 1,
        "pattern": "^[a-z0-9_-]+$",
        "type": "string"
      }
    },
    "verbosity": {
      "default": "standard",
      "description": "How much of the response envelope to return: minimal (ids/text/totals only), standard (the default), full (adds per-dimension score attribution and timings). Shapes the RESPONSE only, never what is generated, persisted, hashed for idempotency, or charged.",
      "enum": [
        "minimal",
        "standard",
        "full"
      ],
      "title": "Verbosity",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.",
      "title": "Idempotency Key"
    }
  },
  "required": [
    "text"
  ],
  "title": "score_hookArguments",
  "additionalProperties": false
}

score_hooks_batch

Score many hooks ranked with `best`, or compare named SETS. 1 credit per text. 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_summary (same heuristic scorer on every set, never view prediction). Also: platform, tags, verbosity, api_key, idempotency_key. Returns {results, best, ...} or {sets, winner, winner_summary, ...}. Errors: unauthorized, invalid_request, insufficient_credits, rate_limited.

Parameters9

texts	any	optional	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. 1 credit per text either way.
platform	string	optional	Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted.
compare	boolean	optional	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	any	optional	Compare mode input: 2-4 NAMED variant lists, e.g. {"curiosity": ["..."], "contrarian": ["..."]}, each 1-25 texts and <=25 texts across all sets. Requires compare=true and excludes `texts`. Every set is scored by the SAME heuristic scorer, so the winner is a craft comparison, never a view prediction.
topic	any	optional	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 back, and it cannot apply that penalty to a topic it was never told. Omit and the scores are topic-blind, so they will not match the numbers a topic-aware call was charged for.
tags	any	optional	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 later with get_usage(tag=...) / list_hooks(tag=...).
verbosity	string	optional	How much of the response envelope to return: minimal (ids/text/totals only), standard (the default), full (adds per-dimension score attribution and timings). Shapes the RESPONSE only, never what is generated, persisted, hashed for idempotency, or charged.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.
idempotency_key	any	optional	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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.

Raw schema

{
  "type": "object",
  "properties": {
    "texts": {
      "anyOf": [
        {
          "items": {
            "maxLength": 300,
            "minLength": 3,
            "type": "string"
          },
          "maxItems": 25,
          "minItems": 1,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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. 1 credit per text either way.",
      "title": "Texts",
      "minItems": 1,
      "maxItems": 25,
      "items": {
        "maxLength": 300,
        "minLength": 3,
        "type": "string"
      }
    },
    "platform": {
      "default": "tiktok",
      "description": "Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted.",
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "linkedin"
      ],
      "title": "Platform",
      "type": "string"
    },
    "compare": {
      "default": false,
      "description": "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.",
      "title": "Compare",
      "type": "boolean"
    },
    "sets": {
      "anyOf": [
        {
          "additionalProperties": {
            "items": {
              "maxLength": 300,
              "minLength": 3,
              "type": "string"
            },
            "maxItems": 25,
            "minItems": 1,
            "type": "array"
          },
          "maxProperties": 4,
          "minProperties": 2,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Compare mode input: 2-4 NAMED variant lists, e.g. {\"curiosity\": [\"...\"], \"contrarian\": [\"...\"]}, each 1-25 texts and <=25 texts across all sets. Requires compare=true and excludes `texts`. Every set is scored by the SAME heuristic scorer, so the winner is a craft comparison, never a view prediction.",
      "title": "Sets"
    },
    "topic": {
      "anyOf": [
        {
          "maxLength": 200,
          "minLength": 3,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 back, and it cannot apply that penalty to a topic it was never told. Omit and the scores are topic-blind, so they will not match the numbers a topic-aware call was charged for.",
      "title": "Topic",
      "minLength": 3,
      "maxLength": 200
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "maxLength": 40,
            "minLength": 1,
            "pattern": "^[a-z0-9_-]+$",
            "type": "string"
          },
          "maxItems": 5,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 later with get_usage(tag=...) / list_hooks(tag=...).",
      "title": "Tags",
      "maxItems": 5,
      "items": {
        "maxLength": 40,
        "minLength": 1,
        "pattern": "^[a-z0-9_-]+$",
        "type": "string"
      }
    },
    "verbosity": {
      "default": "standard",
      "description": "How much of the response envelope to return: minimal (ids/text/totals only), standard (the default), full (adds per-dimension score attribution and timings). Shapes the RESPONSE only, never what is generated, persisted, hashed for idempotency, or charged.",
      "enum": [
        "minimal",
        "standard",
        "full"
      ],
      "title": "Verbosity",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.",
      "title": "Idempotency Key"
    }
  },
  "title": "score_hooks_batchArguments",
  "additionalProperties": false
}

remix_hook

Rewrite an existing hook into a target archetype. 2 credits per variant. Args: EXACTLY one of text or hook_id; target_archetype OR its alias archetype (disagreeing spellings are a 400); count, tags, verbosity, api_key, idempotency_key. Deterministic; 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, not_found, insufficient_credits, rate_limited.

Parameters11

text	any	optional	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	enum	optional	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, there is no default angle.
count	integer	optional	How many variants to produce, 1-5, at 2 credits each. You are billed only for variants actually returned.
hook_id	any	optional	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 do not have to carry it back. Account-scoped, so an unknown or foreign id is the same not_found get_hook returns. Pass this OR `text`, never both and never neither.
archetype	enum	optional	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 a disagreement is a typed invalid_request rather than a silent winner.
platform	enum	optional	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 elsewhere, so it moves both score.total and the rank order. Each variant's total is then reproducible through score_hook with the SAME platform, and the scale used is echoed back as `platform`. Omit for tiktok (unchanged behaviour).
topic	any	optional	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) that repeats its own subject scores up to 8 points higher without it and the rank order of the pack can differ. Only needed with `text`: a remix by `hook_id` reads the topic off the hook you bought. Sending both is fine when they are equal and a disagreement is a typed invalid_request rather than a silent winner. Omit for unchanged behaviour.
tags	any	optional	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 later with get_usage(tag=...) / list_hooks(tag=...).
verbosity	string	optional	How much of the response envelope to return: minimal (ids/text/totals only), standard (the default), full (adds per-dimension score attribution and timings). Shapes the RESPONSE only, never what is generated, persisted, hashed for idempotency, or charged.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.
idempotency_key	any	optional	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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "anyOf": [
        {
          "maxLength": 300,
          "minLength": 3,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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.",
      "title": "Text",
      "minLength": 3,
      "maxLength": 300
    },
    "target_archetype": {
      "anyOf": [
        {
          "enum": [
            "curiosity_gap",
            "contrarian",
            "data_shock",
            "story",
            "transformation",
            "listicle",
            "authority",
            "urgency"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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, there is no default angle.",
      "title": "Target Archetype",
      "enum": [
        "curiosity_gap",
        "contrarian",
        "data_shock",
        "story",
        "transformation",
        "listicle",
        "authority",
        "urgency",
        null
      ]
    },
    "count": {
      "default": 1,
      "description": "How many variants to produce, 1-5, at 2 credits each. You are billed only for variants actually returned.",
      "maximum": 5,
      "minimum": 1,
      "title": "Count",
      "type": "integer"
    },
    "hook_id": {
      "anyOf": [
        {
          "maxLength": 64,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 do not have to carry it back. Account-scoped, so an unknown or foreign id is the same not_found get_hook returns. Pass this OR `text`, never both and never neither.",
      "title": "Hook Id",
      "maxLength": 64
    },
    "archetype": {
      "anyOf": [
        {
          "enum": [
            "curiosity_gap",
            "contrarian",
            "data_shock",
            "story",
            "transformation",
            "listicle",
            "authority",
            "urgency"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 a disagreement is a typed invalid_request rather than a silent winner.",
      "title": "Archetype",
      "enum": [
        "curiosity_gap",
        "contrarian",
        "data_shock",
        "story",
        "transformation",
        "listicle",
        "authority",
        "urgency",
        null
      ]
    },
    "platform": {
      "anyOf": [
        {
          "enum": [
            "tiktok",
            "instagram",
            "youtube",
            "x",
            "linkedin"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 elsewhere, so it moves both score.total and the rank order. Each variant's total is then reproducible through score_hook with the SAME platform, and the scale used is echoed back as `platform`. Omit for tiktok (unchanged behaviour).",
      "title": "Platform",
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "linkedin",
        null
      ]
    },
    "topic": {
      "anyOf": [
        {
          "maxLength": 200,
          "minLength": 3,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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) that repeats its own subject scores up to 8 points higher without it and the rank order of the pack can differ. Only needed with `text`: a remix by `hook_id` reads the topic off the hook you bought. Sending both is fine when they are equal and a disagreement is a typed invalid_request rather than a silent winner. Omit for unchanged behaviour.",
      "title": "Topic",
      "minLength": 3,
      "maxLength": 200
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "maxLength": 40,
            "minLength": 1,
            "pattern": "^[a-z0-9_-]+$",
            "type": "string"
          },
          "maxItems": 5,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 later with get_usage(tag=...) / list_hooks(tag=...).",
      "title": "Tags",
      "maxItems": 5,
      "items": {
        "maxLength": 40,
        "minLength": 1,
        "pattern": "^[a-z0-9_-]+$",
        "type": "string"
      }
    },
    "verbosity": {
      "default": "standard",
      "description": "How much of the response envelope to return: minimal (ids/text/totals only), standard (the default), full (adds per-dimension score attribution and timings). Shapes the RESPONSE only, never what is generated, persisted, hashed for idempotency, or charged.",
      "enum": [
        "minimal",
        "standard",
        "full"
      ],
      "title": "Verbosity",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.",
      "title": "Idempotency Key"
    }
  },
  "title": "remix_hookArguments",
  "additionalProperties": false
}

list_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), unreported (only hooks a first outcome report can reward), limit (1-100), offset, api_key. Returns {hooks:[{hook_id, text, archetype, mode, score_total, created_at, request_id}], limit, offset, total}. Errors: unauthorized, invalid_request, rate_limited.

Parameters9

mode	enum	optional	Filter to hooks bought from this engine. Canonical stored values: instant\|smart\|research\|remix; the generate aliases (template\|off\|quick, llm\|on\|fast, search\|deep\|deep_research) are accepted and resolved to their canonical value. Omit for every mode.
since	any	optional	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-only string or a unix epoch silently selects the wrong window). Omit for no lower bound.
tag	any	optional	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 wildcard here, and neither is `%`; there is no pattern matching. Omit for every tag.
topic	any	optional	Case-insensitive SUBSTRING match against the topic a hook was generated for (unlike `tag`, which is exact). Omit for every topic.
request_id	any	optional	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 (or its own log) and gets back precisely the hooks that call was charged for, with no guessing by topic or timestamp. An unknown or foreign request_id returns an empty page, never an error.
unreported	any	optional	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	optional	Max hooks to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation.
offset	integer	optional	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. The ceiling is SQLite's largest bindable integer: above it the read could only ever have been a 500, so it is a typed invalid_request instead.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "mode": {
      "anyOf": [
        {
          "enum": [
            "deep",
            "deep_research",
            "fast",
            "instant",
            "llm",
            "off",
            "on",
            "quick",
            "remix",
            "research",
            "search",
            "smart",
            "template"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Filter to hooks bought from this engine. Canonical stored values: instant|smart|research|remix; the generate aliases (template|off|quick, llm|on|fast, search|deep|deep_research) are accepted and resolved to their canonical value. Omit for every mode.",
      "title": "Mode",
      "enum": [
        "deep",
        "deep_research",
        "fast",
        "instant",
        "llm",
        "off",
        "on",
        "quick",
        "remix",
        "research",
        "search",
        "smart",
        "template",
        null
      ]
    },
    "since": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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-only string or a unix epoch silently selects the wrong window). Omit for no lower bound.",
      "title": "Since"
    },
    "tag": {
      "anyOf": [
        {
          "pattern": "^[a-z0-9_-]{1,40}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 wildcard here, and neither is `%`; there is no pattern matching. Omit for every tag.",
      "title": "Tag",
      "pattern": "^[a-z0-9_-]{1,40}$"
    },
    "topic": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Case-insensitive SUBSTRING match against the topic a hook was generated for (unlike `tag`, which is exact). Omit for every topic.",
      "title": "Topic"
    },
    "request_id": {
      "anyOf": [
        {
          "maxLength": 64,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (or its own log) and gets back precisely the hooks that call was charged for, with no guessing by topic or timestamp. An unknown or foreign request_id returns an empty page, never an error.",
      "title": "Request Id",
      "maxLength": 64
    },
    "unreported": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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.",
      "title": "Unreported"
    },
    "limit": {
      "default": 20,
      "description": "Max hooks to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation.",
      "maximum": 200,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "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. The ceiling is SQLite's largest bindable integer: above it the read could only ever have been a 500, so it is a typed invalid_request instead.",
      "maximum": 9223372036854776000,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "list_hooksArguments",
  "additionalProperties": false
}

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	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_found.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "hook_id": {
      "description": "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_found.",
      "title": "Hook Id",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "required": [
    "hook_id"
  ],
  "title": "get_hookArguments",
  "additionalProperties": false
}

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	enum	optional	Filter to outcomes reported for one platform. Omit for all.
since	any	optional	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-only string or a unix epoch silently selects the wrong window). Omit for no lower bound.
hook_id	any	optional	Filter to the outcomes reported against ONE hook (its id from list_hooks / a generate response). Omit for every hook.
limit	integer	optional	Max outcomes to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation.
offset	integer	optional	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. The ceiling is SQLite's largest bindable integer: above it the read could only ever have been a 500, so it is a typed invalid_request instead.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "platform": {
      "anyOf": [
        {
          "enum": [
            "tiktok",
            "instagram",
            "youtube",
            "x",
            "other"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Filter to outcomes reported for one platform. Omit for all.",
      "title": "Platform",
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "other",
        null
      ]
    },
    "since": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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-only string or a unix epoch silently selects the wrong window). Omit for no lower bound.",
      "title": "Since"
    },
    "hook_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Filter to the outcomes reported against ONE hook (its id from list_hooks / a generate response). Omit for every hook.",
      "title": "Hook Id"
    },
    "limit": {
      "default": 50,
      "description": "Max outcomes to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation.",
      "maximum": 200,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "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. The ceiling is SQLite's largest bindable integer: above it the read could only ever have been a 500, so it is a typed invalid_request instead.",
      "maximum": 9223372036854776000,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "list_outcomesArguments",
  "additionalProperties": false
}

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	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	required	Where the hook was actually posted. Required.
posted_at	string	required	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	required	Views the post had accrued at report time, >=0. Required: it is the only field the corpus calibrates against. Report again later (up to 20 reports per hook) to record how it matured.
likes	any	optional	Likes at report time, >=0. Omit if you cannot read it.
retention_pct	any	optional	Average view-through as a PERCENT, 0-100 (not a 0-1 fraction). Omit if the platform does not expose it.
url	any	optional	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	any	optional	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 (the stdio default). No key resolvable -> unauthorized.
idempotency_key	any	optional	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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.

Raw schema

{
  "type": "object",
  "properties": {
    "hook_id": {
      "description": "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.",
      "title": "Hook Id",
      "type": "string"
    },
    "platform": {
      "description": "Where the hook was actually posted. Required.",
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "other"
      ],
      "title": "Platform",
      "type": "string"
    },
    "posted_at": {
      "description": "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.",
      "title": "Posted At",
      "type": "string"
    },
    "views": {
      "description": "Views the post had accrued at report time, >=0. Required: it is the only field the corpus calibrates against. Report again later (up to 20 reports per hook) to record how it matured.",
      "minimum": 0,
      "title": "Views",
      "type": "integer"
    },
    "likes": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Likes at report time, >=0. Omit if you cannot read it.",
      "title": "Likes",
      "minimum": 0
    },
    "retention_pct": {
      "anyOf": [
        {
          "maximum": 100,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Average view-through as a PERCENT, 0-100 (not a 0-1 fraction). Omit if the platform does not expose it.",
      "title": "Retention Pct",
      "minimum": 0,
      "maximum": 100
    },
    "url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Public http(s) URL of the post, for your own audit trail. Must carry a host; omit entirely rather than passing a placeholder.",
      "title": "Url"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.",
      "title": "Idempotency Key"
    }
  },
  "required": [
    "hook_id",
    "platform",
    "posted_at",
    "views"
  ],
  "title": "report_outcomeArguments",
  "additionalProperties": false
}

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 is invalid_request. A job only runs where a job worker runs: when none does the response carries worker_alive:false + a warning, so call generate_hooks instead. Errors: unauthorized, invalid_request, insufficient_credits, idempotency_conflict.

Parameters10

topic	any	optional	Single subject for the job, 3-200 chars. Pass EITHER this or `topics`, never both and never neither.
topics	any	optional	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	optional	Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted.
count	integer	optional	Hooks per topic, 1-25. With `topics` this applies to every subject, so the job's cost scales with count * len(topics).
archetypes	any	optional	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 deliberately narrowing a deck.
style	any	optional	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, so it cannot change the voice there. Omit for the engine's default register.
mode	enum	optional	Generation engine and therefore the price: instant (0 base + 1/hook, deterministic templates, sub-second), smart (0 + 2/hook, one LLM call, seconds), research (10 + 4/hook, brief->draft->judge, tens of seconds). Aliases: template\|off\|quick->instant, llm\|on\|fast->smart, search\|deep\|deep_research->research. Omit (or auto) -> smart when an LLM key is configured, else instant.
tags	any	optional	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 later with get_usage(tag=...) / list_hooks(tag=...).
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.
idempotency_key	any	optional	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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.

Raw schema

{
  "type": "object",
  "properties": {
    "topic": {
      "anyOf": [
        {
          "maxLength": 200,
          "minLength": 3,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Single subject for the job, 3-200 chars. Pass EITHER this or `topics`, never both and never neither.",
      "title": "Topic",
      "minLength": 3,
      "maxLength": 200
    },
    "topics": {
      "anyOf": [
        {
          "items": {
            "maxLength": 200,
            "minLength": 3,
            "type": "string"
          },
          "maxItems": 20,
          "minItems": 1,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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`.",
      "title": "Topics",
      "minItems": 1,
      "maxItems": 20,
      "items": {
        "maxLength": 200,
        "minLength": 3,
        "type": "string"
      }
    },
    "platform": {
      "default": "tiktok",
      "description": "Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted.",
      "enum": [
        "tiktok",
        "instagram",
        "youtube",
        "x",
        "linkedin"
      ],
      "title": "Platform",
      "type": "string"
    },
    "count": {
      "default": 10,
      "description": "Hooks per topic, 1-25. With `topics` this applies to every subject, so the job's cost scales with count * len(topics).",
      "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,
      "description": "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 deliberately narrowing a deck.",
      "title": "Archetypes",
      "items": {
        "enum": [
          "curiosity_gap",
          "contrarian",
          "data_shock",
          "story",
          "transformation",
          "listicle",
          "authority",
          "urgency"
        ],
        "type": "string"
      }
    },
    "style": {
      "anyOf": [
        {
          "description": "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, so it cannot change the voice there. Omit for the engine's default register.",
          "maxLength": 200,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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, so it cannot change the voice there. Omit for the engine's default register.",
      "title": "Style",
      "maxLength": 200
    },
    "mode": {
      "anyOf": [
        {
          "enum": [
            "instant",
            "template",
            "off",
            "quick",
            "smart",
            "llm",
            "on",
            "fast",
            "research",
            "search",
            "deep",
            "deep_research",
            "auto"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Generation engine and therefore the price: instant (0 base + 1/hook, deterministic templates, sub-second), smart (0 + 2/hook, one LLM call, seconds), research (10 + 4/hook, brief->draft->judge, tens of seconds). Aliases: template|off|quick->instant, llm|on|fast->smart, search|deep|deep_research->research. Omit (or auto) -> smart when an LLM key is configured, else instant.",
      "title": "Mode",
      "enum": [
        "instant",
        "template",
        "off",
        "quick",
        "smart",
        "llm",
        "on",
        "fast",
        "research",
        "search",
        "deep",
        "deep_research",
        "auto",
        null
      ]
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "maxLength": 40,
            "minLength": 1,
            "pattern": "^[a-z0-9_-]+$",
            "type": "string"
          },
          "maxItems": 5,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 later with get_usage(tag=...) / list_hooks(tag=...).",
      "title": "Tags",
      "maxItems": 5,
      "items": {
        "maxLength": 40,
        "minLength": 1,
        "pattern": "^[a-z0-9_-]+$",
        "type": "string"
      }
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.",
      "title": "Idempotency Key"
    }
  },
  "title": "start_generate_jobArguments",
  "additionalProperties": false
}

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	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 not_found.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "description": "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 not_found.",
      "title": "Job Id",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "get_jobArguments",
  "additionalProperties": false
}

wait_for_job

Block until a job is terminal, then return it. Free, bounded, no poll loop. Returns the EXACT get_job body plus timed_out, waited_ms and polls, so 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 job_id. Waiting neither cancels nor charges; the worker charges when it runs the job either way. It returns IMMEDIATELY with worker_alive:false + `warning` when no worker exists here. Errors: unauthorized, not_found (unknown or foreign job_id), rate_limited.

Parameters3

job_id	string	required	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 as not_found.
timeout_seconds	integer	optional	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 error: you get timed_out:true plus the job's live state.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "description": "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 as not_found.",
      "title": "Job Id",
      "type": "string"
    },
    "timeout_seconds": {
      "default": 60,
      "description": "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 error: you get timed_out:true plus the job's live state.",
      "maximum": 300,
      "minimum": 1,
      "title": "Timeout Seconds",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "wait_for_jobArguments",
  "additionalProperties": false
}

cancel_job

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. Cancelled reads as status "failed" with error.error.details.cancelled true; to re-run, resubmit with a FRESH idempotency_key (reusing the cancelled one replays the cancelled result). Errors: unauthorized, forbidden (key lacks the spend scope), not_found, rate_limited.

Parameters2

job_id	string	required	The job to cancel. Account-scoped: an id you do not own reads as not_found, exactly like get_job.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "description": "The job to cancel. Account-scoped: an id you do not own reads as not_found, exactly like get_job.",
      "title": "Job Id",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "cancel_jobArguments",
  "additionalProperties": false
}

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	Max jobs to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation.
offset	integer	optional	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. The ceiling is SQLite's largest bindable integer: above it the read could only ever have been a 500, so it is a typed invalid_request instead.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 50,
      "description": "Max jobs to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation.",
      "maximum": 200,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "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. The ceiling is SQLite's largest bindable integer: above it the read could only ever have been a 500, so it is a typed invalid_request instead.",
      "maximum": 9223372036854776000,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "list_jobsArguments",
  "additionalProperties": false
}

set_webhook

Register (or replace) this account's webhook; the secret is returned ONCE. Admin scope. VHGENGINE 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: sha256=HMAC_SHA256(secret, raw_body); a webhook.test pings. Args: url (1-2048), api_key (admin). Cost=free. Errors: unauthorized, forbidden, invalid_request, rate_limited. Returns {url, secret, created_at, events, note, test_delivery_id}.

Parameters2

url	string	required	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, so this is not safe to blind-retry.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "description": "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, so this is not safe to blind-retry.",
      "maxLength": 2048,
      "minLength": 1,
      "title": "Url",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "required": [
    "url"
  ],
  "title": "set_webhookArguments",
  "additionalProperties": false
}

get_webhook

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.

Parameters1

api_key

any

optional

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "get_webhookArguments",
  "additionalProperties": false
}

delete_webhook

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.

Parameters1

api_key

any

optional

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "delete_webhookArguments",
  "additionalProperties": false
}

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	enum	optional	Filter to deliveries in this state: pending (queued, not yet attempted), retrying (failed, backing off), delivered (2xx), dead (retries exhausted; redrive_webhook_delivery can requeue it), retired. Omit for all.
limit	integer	optional	Max deliveries to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation.
offset	integer	optional	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. The ceiling is SQLite's largest bindable integer: above it the read could only ever have been a 500, so it is a typed invalid_request instead.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "anyOf": [
        {
          "enum": [
            "pending",
            "retrying",
            "delivered",
            "dead",
            "retired"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Filter to deliveries in this state: pending (queued, not yet attempted), retrying (failed, backing off), delivered (2xx), dead (retries exhausted; redrive_webhook_delivery can requeue it), retired. Omit for all.",
      "title": "Status",
      "enum": [
        "pending",
        "retrying",
        "delivered",
        "dead",
        "retired",
        null
      ]
    },
    "limit": {
      "default": 50,
      "description": "Max deliveries to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation.",
      "maximum": 200,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "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. The ceiling is SQLite's largest bindable integer: above it the read could only ever have been a 500, so it is a typed invalid_request instead.",
      "maximum": 9223372036854776000,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "list_webhook_deliveriesArguments",
  "additionalProperties": false
}

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	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_found.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "delivery_id": {
      "description": "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_found.",
      "title": "Delivery Id",
      "type": "string"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "required": [
    "delivery_id"
  ],
  "title": "redrive_webhook_deliveryArguments",
  "additionalProperties": false
}

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	Max completed rows in `recent`, 1-100. Does not limit `in_flight`, which always shows everything currently running.
api_key	any	optional	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 (the stdio default). No key resolvable -> unauthorized.

Raw schema

{
  "type": "object",
  "properties": {
    "recent_limit": {
      "default": 20,
      "description": "Max completed rows in `recent`, 1-100. Does not limit `in_flight`, which always shows everything currently running.",
      "maximum": 100,
      "minimum": 1,
      "title": "Recent Limit",
      "type": "integer"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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 (the stdio default). No key resolvable -> unauthorized.",
      "title": "Api Key"
    }
  },
  "title": "get_activityArguments",
  "additionalProperties": false
}

Install

Tools (38)

signupgetting_startedlist_archetypespricingget_estimateshealthget_accountget_usage

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://engine-production-3bdc.up.railway.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "vhgengine": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://engine-production-3bdc.up.railway.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

MCP Server: app.railway.up.engine-production-3bdc/vhgengine

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

signup

getting_started

list_archetypes

pricing

get_estimates

health

get_account

get_usage

export_usage

list_runs

quote

add_credits

list_billing_events

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

wait_for_job

cancel_job

list_jobs

set_webhook

get_webhook

delete_webhook

list_webhook_deliveries

redrive_webhook_delivery

get_activity

Install

Remote endpoint

Related servers