hookdetector.com

VHGENGINE - agents-first viral-hook engine. You are the customer; there is no human in a browser. Every step is machine-driven. GETTING STARTED 1. Call signup(beta_access_code="<YOUR-8-DIGIT-CODE>", idempotency_key="unique-retry-key", name=...) -> api_key. Substitute the code issued to you. The placeholder is deliberately NOT eight digits: an eight-digit guess passes schema validation, reaches signup, and spends a durable rate-limited attempt before the code is ever tested, returning 403 beta_access_denied. Standard access includes ten free product requests; owner access is unlimited. Signup retains 500 credits as a compatibility balance for historical ledgers, but beta operations charge zero. Exact signup replay recovers the same derived key. 2. Authenticate every other tool: pass api_key="..." on the call, OR send Authorization: Bearer <key> over HTTP, OR set VHGENGINE_API_KEY (stdio default). An unauthorized envelope carries details.reason (no_credential | revoked | unknown_key | deleted) and a hint naming the fix for THAT one. reason="revoked" means your account is intact: use list_keys / create_key, do NOT sign up again. 3. Call getting_started (free, no auth) for the evidence quickstart and archive boundary. ARCHIVED QUOTE METADATA: quote can still parse historical generation inputs and prices, but it cannot authorize or predict a runnable writer. Do not use it as a fallback for missing source evidence. VERIFIED EVIDENCE: research_hook_evidence requests up to thirty verified public source examples, separate from generated hooks. It publishes hard-gate and ranking receipts, never pads a short result, and accepts language, locale, format, source-minimum, and opener-verification policy. Where the approved provider runtime is bound, the call DISPATCHES to that provider and SPENDS vendor credits, bounded by a 600-second authorization: allow at least 610 seconds and do not re-ask with a fresh idempotency_key while it is still running. A 502 after about 300 seconds is the transport cutting a response that has sent no bytes, not the commission failing: the run finishes and is charged, so replay the same idempotency_key to receive the completed result at no additional charge. Where that runtime is not bound, the call makes no provider dispatch at all. Call health and read hook_research_provider_ready to see which posture you are on. unsupported_cell always means no provider call was made and the charge is zero, either because the request carries a planning deficiency or because that runtime is unavailable here. ARCHIVED MODES + COST / PRIVATE-BETA PRICING (base + per_hook * hooks_returned): instant 0+0/hook, smart 0+0/hook, research 0+0/hook, 0 at count=10. Customer pricing is zero. Aliases and wait fields remain stored-client metadata. Pricing rows keep literal {base, per_hook} fields for compatibility. Every generation, batch, job, and remix writer fails before work or billing. Reads (getting_started, pricing, get_estimates, list_archetypes, get_account, get_usage, get_activity, get_job, list_jobs, list_keys, list_hooks, get_hook, list_outcomes, list_runs, list_billing_events, list_creator_profiles, get_creator_profile, health) are free. LOST A RESPONSE? list_runs(request_id=...) is the receipt for any call you were charged for, newest first; follow its `hooks_url` for the hooks that call produced instead of re-running (and re-charging) the request. Bought hooks are retrievable for 90 days via list_hooks / get_hook (kept indefinitely once you report an outcome on them); list_hooks(mode=) takes the legacy generation vocabulary, aliases included, and resolves each to the stored instant|smart|research|remix, while list_hooks(tag=) is an exact literal slug match ("_" is a tag character, not a wildcard). Report what a hook actually did once posted with report_outcome (free; caller-supplied and not independently verified, retained for future calibration, but not consumed by generation, scoring, or retrieval today and no view prediction is claimed; list_hooks(unreported=true) finds rewardable hooks); read your reported outcomes in bulk with list_outcomes. Manage API keys with create_key / list_keys / revoke_key (free). Keep reusable, account-owned creator declarations with create_creator_profile / list_creator_profiles / get_creator_profile / update_creator_profile / delete_creator_profile. These versioned caller declarations and deny-by-default secondary-use decisions are stored for governance; VHGENGINE does not verify authority, and learning/retrieval do not consume them today. Export the ledger, every hook/immutable served instance/non-prose lineage marker/outcome, and retained jobs, commissions, and request tags in ONE call with export_usage, then leave cleanly with delete_account (terminal; keeps the financial ledger and de-associates outcomes from the account while retaining their submitted content, URLs, and tags in the shared corpus). ARCHIVED WAIT GUIDANCE: expected_wait {p50_ms, p90_ms, source}, progressToken, and generation-job fields remain readable for stored clients. No archived writer starts, streams progress, or queues work. SOURCE-FREE GENERATION IS ARCHIVED. generate_hooks, generate_hooks_batch, remix_hook, and start_generate_job fail before model, provider, queue, persistence, or billing work. They cannot create substitutes for missing research supply, so cancellation cannot leave hidden generated hooks or charges. Use research_hook_evidence with an idempotency_key; it returns only source-proven public footage or an honest shortfall/unsupported outcome. ERRORS are one typed envelope: {"error": {code, message, retriable, retry_after_seconds, details (with a next-action hint), request_id}}. Common codes: unauthorized, forbidden (key lacks the scope), beta_access_denied, beta_quota_exhausted, invalid_request, not_found, conflict, insufficient_credits (retained compatibility error; customer operations are zero-priced during beta), llm_unavailable (legacy compatibility error, never an evidence fallback), configuration_unavailable (the operator must install a required security secret), capability_disabled (the operation is defined but its measured writer remains off), idempotency_conflict, rate_limited (honor retry_after_seconds; get_account.rate_limit shows the remaining window so a fleet can pace BEFORE being throttled), internal. Each tool's docstring lists the errors it can return. A failed resource read (vhgengine://...) carries the SAME envelope in the JSON-RPC error's `data` field, with the message repeated in `message`. SCHEMAS: every tool advertises both an inputSchema (per-argument descriptions, enums and bounds) and an outputSchema naming the keys it returns. Read them instead of guessing, and instead of paying for a call to discover a field name. IDEMPOTENCY: pass idempotency_key on signup / generate_hooks / generate_hooks_batch / research_hook_evidence / score_hook / score_hooks_batch / remix_hook / add_credits / start_generate_job / report_outcome / create_creator_profile / update_creator_profile / delete_creator_profile; a replay returns the stored result (replayed:true) and never applies the write twice or re-charges. Profile deletion erases its old create/update replay bodies; reusing one of those keys fails closed with idempotency_conflict and reason=resource_deleted instead of recreating the profile.

Find short-form hooks that already work. Call create_account once to get an api_key, then send it as the header 'Authorization: Bearer hd_...' or pass it as the api_key argument. find_hooks starts a run that takes about 2 to 3 minutes; then call get_run with wait_seconds=50 until status is done or failed (usually 3 or 4 calls). Pass an idempotency_key to find_hooks so a retry never starts a second run. export_run turns a finished run into CSV, JSON or Markdown. Every error's whole text is JSON {"error": {"code": <HTTP status>, "message", "error_code"}}, plus "errors" with each field's loc on a 422; branch on error_code. A key holds some of four permissions (read, write, research, admin); a call it lacks is 403 insufficient_scope. Full guide: GET /llms.txt; the whole manual as one file: GET /docs.md.