VHGENGINE

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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

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

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

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.

List the hooks this account has bought, newest first. Free (WP-G). Persisted hooks stay retrievable for 90 days. Args: mode (instant|smart|research| remix, or any generate alias such as template/search), since (ISO timestamp), tag (exact fleet-tag match), topic (substring), unreported (true: only hooks a first outcome report can still 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.