API reference

11 JSON-RPC methods. Render HTML, capture URLs, compile diagrams — permanent shareable links.

Quick Reference

Endpoint
POST https://vhiz.dev/
Protocol
JSON-RPC 2.0 — one call per request, no batch
Auth
Authorization: Bearer vhiz_...
Call create-token first (no auth needed) to get a token with 50 free credits (100 with email).
Envelope
{
  "jsonrpc": "2.0",
  "method": "method-name",
  "params": { ... },
  "id": 1
}
Credit tiers
Cost based on total output megapixels (width × height × dpr² / 1M):
≤4 MP → 1 credit · 4–9 MP → 2 credits · 9–16 MP → 3 credits
Budget ceiling: 16 MP per request.
dry_run
Any method accepts dry_run: true — returns the full response shape (cost, normalized params) without executing or charging credits.
accounting
Every authenticated response includes accounting: { credits_before, cost, credits_after, megapixels }. megapixels present for tiered methods only.
resolved
Every authenticated response includes resolved — the final normalized parameters (defaults filled, values clamped). Content params (html, definition) are excluded.

Getting started

create-token

no auth free

Self-service token provisioning. No auth required. Each token is a customer record from the moment it's minted.

Parameters

ParamTypeDescription
email string Unlocks 100 credits (vs 50 anonymous). Enables credit purchase when verification is live.
name string Display name for the token holder.

Result

token string
credits integer
Starting balance (50 anonymous, 100 with email).
base_cost number
Base cost per call in credits.
Anonymous token
curl https://vhiz.dev/ \
  -H 'Content-Type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "method": "create-token",
  "params": {},
  "id": 1
}'
{
  "jsonrpc": "2.0",
  "result": {
    "token": "vhiz_k7m2x9p4q1w6n3b8y5a",
    "credits": 50,
    "base_cost": 1
  },
  "id": 1
}

check-token

auth required free

Verify a token and see what's on it. Free to call.

Parameters

No parameters.

Result

credits integer
base_cost number

add-credits

auth required free

Top up token balance with free credits. Max 5 per call.

Parameters

ParamTypeDescription
amountrequired integer Credits to add (1–5). 1–5

Result

credited integer
Number of credits added.
credits_before integer
Balance before addition.
credits_after integer
Balance after addition.
Errors (3)
CodeWhenMessage
-32602 missing amount missing required param: amount (integer 1–5)
-32602 invalid amount invalid amount: {n} (must be integer 1–5)
-32602 amount exceeds max invalid amount: {n} (max 5 per call)
Add 3 credits
curl https://vhiz.dev/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer vhiz_YOUR_TOKEN' \
  -d '{
  "jsonrpc": "2.0",
  "method": "add-credits",
  "params": {
    "amount": 3
  },
  "id": 1
}'
{
  "jsonrpc": "2.0",
  "result": {
    "credited": 3,
    "credits_before": 50,
    "credits_after": 53,
    "accounting": {
      "credits_before": 50,
      "cost": 0,
      "credits_after": 53
    }
  },
  "id": 1
}

Create methods

create-render

auth required 1-3 credits

HTML/CSS → image or PDF with shareable link. Supports versioning (up to 50 per render ID).

Parameters

ParamTypeDescription
htmlrequired string HTML markup to render.
format png · jpeg · pdf Output format. default: "png"
width integer Viewport width in CSS pixels. default: 1280 1–8192
height string|integer Canvas height. 'auto' fits to content (clamped to megapixel budget). Integer value 1-8192. default: "auto"
dpr integer Device pixel ratio. default: 1 1–3
timeout integer Render timeout in seconds. default: 30 1–60
title string Display name for share page.
id string Existing render ID to append new version. Omit to create new render. Caller may also supply a new ID following render_ + 16 hex convention — validated for format and uniqueness. format: render_id

Result

id string
version integer
page string
Share page URL.
manifest string
Manifest URL for later retrieval.
artifact string
Direct artifact URL. Dynamic filename encodes resolved dimensions: screen{W}x{H}@{S}x.{format}
format string
width integer
height integer
dpr integer
size_bytes integer
console array
Browser console output from rendering the HTML. Each entry has type (log/warning/error/info/debug/exception), args (typed RemoteObject array), text (flattened one-liner), and timestamp. Empty array if no console activity.
resolved object
Echoed normalized rendering params: { format, width, height, dpr }.
accounting object
Credits before/cost/after, plus megapixels.
Errors (10)
CodeWhenMessage
-32602 missing html missing required param: html
create-render takes {html: string, format?: 'png'|'jpeg'|'pdf', width?: 1-8192, height?: 1-8192|'auto', dpr?: 1-3, total ≤16 MP}
-32602 invalid format invalid format: must be png, jpeg, or pdf
-32602 invalid width invalid width: must be integer 1-8192
-32602 invalid height invalid height: must be integer 1-8192 or 'auto'
-32602 invalid dpr invalid dpr: must be integer 1-3
-32602 megapixel budget exceeded image exceeds 16 megapixel budget: {W}×{H}×{dpr}² = {MP} MP. Reduce width, height, or dpr.
-32602 render not found render not found: {id}
-32003 pool exhausted all render slots occupied. Try again shortly.
-32004 timeout render timed out after {n}s (set timeout param to increase, max 60)
-32603 engine failure render engine failed (exit {code})
First render
curl https://vhiz.dev/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer vhiz_YOUR_TOKEN' \
  -d '{
  "jsonrpc": "2.0",
  "method": "create-render",
  "params": {
    "html": "<h1>hello</h1>"
  },
  "id": 1
}'
{
  "jsonrpc": "2.0",
  "result": {
    "id": "render_a1b2c3d4e5f60718",
    "version": 1,
    "page": "https://vhiz.dev/render_a1b2c3d4e5f60718",
    "manifest": "https://vhiz.dev/render_a1b2c3d4e5f60718.json",
    "artifact": "https://vhiz.dev/render_a1b2c3d4e5f60718/v/1/screen1280x720@1x.png",
    "format": "png",
    "width": 1280,
    "height": 720,
    "dpr": 1,
    "size_bytes": 34521,
    "resolved": {
      "format": "png",
      "width": 1280,
      "height": "auto",
      "dpr": 1
    },
    "accounting": {
      "credits_before": 50,
      "cost": 1,
      "credits_after": 49,
      "megapixels": 0.92
    }
  },
  "id": 1
}

create-capture

auth required 1-3 credits

Capture a live URL to image or PDF with shareable link. Navigates headless Chrome to the URL, screenshots the result, and extracts semantic artifacts: text, cleaned DOM, network trace, page head data, asset inventory, link enumeration, HTTP response headers, raw HTTP response body, and browser console output.

Parameters

ParamTypeDescription
urlrequired string URL to capture. Auto-prepends https:// if missing scheme.
format png · jpeg · pdf Output format. default: "png"
width integer Single-viewport shorthand. When provided without viewports, captures one viewport at this width. When both absent, defaults to viewports [375, 768, 1280]. default: 1280 1–8192
height string|integer Canvas height. 'auto' fits to content (clamped to megapixel budget). Integer value 1-8192. default: "auto"
dpr integer Device pixel ratio. default: 1 1–3
timeout integer Capture timeout in seconds. default: 30 1–60
id string Caller-supplied capture ID following capture_ + 16 hex convention. Validated for format and uniqueness. format: capture_id
viewports array Viewport sizes for capture. Each element is an integer (width shorthand — height auto, dpr 1) or an object { width, height?, dpr? }. Default: [375, 768, 1280] (mobile, tablet, desktop). Max 10. Navigate once, resize+screenshot per viewport. Billing: total megapixels across all screenshots determines tier. default: [375,768,1280] max 10 items
actions array Ordered sequence of page interactions executed after page load and network idle, before the final screenshot. Each action optionally captures a window-sized screenshot at that state. Cannot be combined with viewports. max 20 items
actionrequired scroll · click Action type.
y integer Scroll target (absolute Y position). Required for scroll actions.
selector string CSS selector for click target (resolved to element center). Required for click actions.
capture boolean Whether to capture a screenshot after this action. Set false for intermediate actions (e.g. click a tab, then scroll to final position). default: true

Result

id string
page string
Share page URL.
manifest string
Manifest URL for later retrieval.
artifacts object
Artifact URLs organized by category. Enrichment files may 404 if extraction failed.
screenshots array
Screenshot URLs, one per viewport. Filename encodes dimensions: screen{W}x{H}@{S}x.{format}
actions array
Action screenshot URLs, present only when params.actions was provided. Numbered by action index: /{id}/actions/{i}.{format}. Only includes actions where capture was true. Window-sized (clipped to viewport at scroll position, not full page).
source
raw string
Raw HTTP response body (pre-JS).
extract
dom string
Cleaned post-JS DOM tree (no scripts/styles/classes).
text string
Lynx-like text render (innerText).
network string
Sub-resource trace (URL, type, status, size, timing).
assets string
Page assets grouped by type (images, stylesheets, scripts, fonts).
links string
All anchor hrefs with text, rel, local/remote flag.
head string
Page head data: title, description, OG tags, canonical URL, favicon URL.
headers string
HTTP response headers from the primary navigation: status code, final URL (after redirects), and full header map.
console string
Browser console output (console.log/warn/error/info/debug and uncaught exceptions). Each entry has type, args (typed RemoteObject array preserving primitives, objects, and previews), text (flattened one-liner), and CDP timestamp.
format string
width integer
height integer
dpr integer
size_bytes integer
resolved object
Echoed normalized params.
accounting object
Credits before/cost/after, plus megapixels.
Errors (17)
CodeWhenMessage
-32602 missing url missing required param: url
create-capture takes {url: string, format?: 'png'|'jpeg'|'pdf', width?: 1-8192, height?: 1-8192|'auto', dpr?: 1-3, viewports?: [...], total ≤16 MP}
-32602 invalid format invalid format: must be png, jpeg, or pdf
-32602 invalid width invalid width: must be integer 1-8192
-32602 invalid height invalid height: must be integer 1-8192 or 'auto'
-32602 invalid dpr invalid dpr: must be integer 1-3
-32602 megapixel budget exceeded image exceeds 16 megapixel budget: {W}×{H}×{dpr}² = {MP} MP. Reduce width, height, or dpr.
-32602 actions + viewports actions and viewports cannot be combined
-32602 actions limit exceeded actions array exceeds 20-entry limit
-32602 missing action type actions[{i}]: missing action type
-32602 unknown action type actions[{i}]: unknown action type (expected scroll or click)
-32602 scroll missing y actions[{i}]: scroll requires y (integer 0–100000)
-32602 scroll y out of range actions[{i}]: scroll y must be integer 0–100000
-32602 click missing selector actions[{i}]: click requires selector (string)
-32602 selector too long actions[{i}]: selector exceeds 256-char limit
-32003 pool exhausted all capture slots occupied. Try again shortly.
-32004 timeout capture timed out after {n}s (set timeout param to increase, max 60)
-32603 engine failure capture engine failed (exit {code})
Default capture (3 responsive viewports)
curl https://vhiz.dev/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer vhiz_YOUR_TOKEN' \
  -d '{
  "jsonrpc": "2.0",
  "method": "create-capture",
  "params": {
    "url": "https://calmcode.io"
  },
  "id": 1
}'
{
  "jsonrpc": "2.0",
  "result": {
    "id": "capture_a1b2c3d4e5f60718",
    "page": "https://vhiz.dev/capture_a1b2c3d4e5f60718",
    "manifest": "https://vhiz.dev/capture_a1b2c3d4e5f60718.json",
    "artifacts": {
      "screenshots": [
        "https://vhiz.dev/capture_a1b2c3d4e5f60718/output/screen375x2400@1x.png",
        "https://vhiz.dev/capture_a1b2c3d4e5f60718/output/screen768x1200@1x.png",
        "https://vhiz.dev/capture_a1b2c3d4e5f60718/output/screen1280x800@1x.png"
      ],
      "source": {
        "raw": "https://vhiz.dev/capture_a1b2c3d4e5f60718/source/raw.html"
      },
      "extract": {
        "dom": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/dom.html",
        "text": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/text.txt",
        "network": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/network.json",
        "assets": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/assets.json",
        "links": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/links.json",
        "head": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/head.json",
        "headers": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/headers.json",
        "console": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/console.json"
      }
    },
    "format": "png",
    "dpr": 1,
    "resolved": {
      "url": "https://calmcode.io",
      "format": "png",
      "viewports": [
        375,
        768,
        1280
      ],
      "dpr": 1
    },
    "accounting": {
      "credits_before": 50,
      "cost": 1,
      "credits_after": 49,
      "megapixels": 2.84
    }
  },
  "id": 1
}

create-diagram

auth required 1-3 credits

Diagram definition → image or PDF with shareable link. Supports Mermaid, D2, and Sugiyama-Tagawa-Toda syntax. Versioning (up to 50 per diagram ID).

Parameters

ParamTypeDescription
definitionrequired string Diagram source in the specified language. Mermaid syntax by default; D2 syntax when language is "d2"; edge-list syntax when language is "sugiyama-tagawa-toda" (one edge per line, e.g. "A -> B").
language mermaid · d2 · sugiyama-tagawa-toda Diagram language. default: "mermaid"
theme string Diagram theme. Valid values depend on language. Mermaid: "default" (default), "dark", "forest", "neutral". D2: "neutral-default" (default), "neutral-grey", "flagship-terrastruct", "cool-classics", "mixed-berry-blue", "grape-soda", "aubergine", "colorblind-clear", "vanilla-nitro-cola", "orange-creamsicle", "shirley-temple", "earth-tones", "everglade-green", "buttered-toast", "dark-mauve", "dark-flagship-terrastruct", "terminal", "terminal-grayscale", "origami", "c4". Sugiyama-Tagawa-Toda: "default" (only option). default: "varies"
background white · transparent Background color. 'transparent' produces a transparent PNG (ignored for JPEG and PDF). default: "white"
format png · jpeg · pdf · svg Output format. SVG produces vector output (resolution-independent, no Chrome rasterization for D2). Always costs 1 credit. default: "png"
width integer Canvas width in CSS pixels. The diagram is rendered into this width; height is determined by content unless explicitly set. default: 1280 1–8192
height string|integer Canvas height. 'auto' fits to diagram content (clamped to megapixel budget). Integer value 1-8192. default: "auto"
dpr integer Device pixel ratio. Defaults to 2 for crisp text in diagrams. default: 2 1–3
timeout integer Render timeout in seconds. default: 30 1–60
title string Display name for share page.
id string Existing diagram ID to append new version. Omit to create new diagram. Caller may also supply a new ID following diagram_ + 8 base62 convention — validated for format and uniqueness. format: diagram_id

Result

id string
version integer
page string
Share page URL.
manifest string
Manifest URL for later retrieval.
artifact string
Direct artifact URL. Dynamic filename encodes resolved dimensions: screen{W}x{H}@{S}x.{format}
format string
width integer
height integer
dpr integer
size_bytes integer
resolved object
Echoed normalized params: { language, theme, background, format, width, height, dpr }.
accounting object
Credits before/cost/after, plus megapixels.
Errors (15)
CodeWhenMessage
-32602 missing definition missing required param: definition
create-diagram takes {definition: string, language?: 'mermaid'|'d2'|'sugiyama-tagawa-toda', theme?: (engine-specific), format?: 'png'|'jpeg'|'pdf'|'svg', width?: 1-8192, height?: 1-8192|'auto', dpr?: 1-3, total ≤16 MP}
-32602 invalid language unsupported language: {lang}. Supported: "mermaid", "d2", "sugiyama-tagawa-toda".
-32602 invalid theme (mermaid) invalid theme: {theme}. Must be default, dark, forest, or neutral.
-32602 invalid theme (d2) invalid D2 theme: {theme}. See API docs for valid D2 theme names.
-32602 invalid background invalid background: must be white or transparent
-32602 invalid format invalid format: must be png, jpeg, pdf, or svg
-32602 invalid width invalid width: must be integer 1-8192
-32602 invalid height invalid height: must be integer 1-8192 or 'auto'
-32602 invalid dpr invalid dpr: must be integer 1-3
-32602 megapixel budget exceeded image exceeds 16 megapixel budget: {W}×{H}×{dpr}² = {MP} MP. Reduce width, height, or dpr.
-32602 parse error diagram parse error: {details}
The definition could not be parsed as valid {language} syntax. Mermaid docs: https://mermaid.js.org/syntax/flowchart.html — D2 docs: https://d2lang.com — Sugiyama-Tagawa-Toda: one edge per line, e.g. "A -> B"
-32602 diagram not found diagram not found: {id}
-32003 pool exhausted all render slots occupied. Try again shortly.
-32004 timeout diagram timed out after {n}s (set timeout param to increase, max 60)
-32603 engine failure diagram engine failed (exit {code})
Flowchart
curl https://vhiz.dev/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer vhiz_YOUR_TOKEN' \
  -d '{
  "jsonrpc": "2.0",
  "method": "create-diagram",
  "params": {
    "definition": "flowchart LR\n  A[Start] --> B{Decision}\n  B -->|Yes| C[Do something]\n  B -->|No| D[Do something else]\n  C --> E[End]\n  D --> E"
  },
  "id": 1
}'
{
  "jsonrpc": "2.0",
  "result": {
    "id": "diagram_Kp4wLn9R",
    "version": 1,
    "page": "https://vhiz.dev/diagram_Kp4wLn9R",
    "manifest": "https://vhiz.dev/diagram_Kp4wLn9R.json",
    "artifact": "https://vhiz.dev/diagram_Kp4wLn9R/v/1/screen1280x420@2x.png",
    "format": "png",
    "width": 1280,
    "height": 420,
    "dpr": 2,
    "size_bytes": 48230,
    "resolved": {
      "language": "mermaid",
      "theme": "default",
      "background": "white",
      "format": "png",
      "width": 1280,
      "height": "auto",
      "dpr": 2
    },
    "accounting": {
      "credits_before": 50,
      "cost": 1,
      "credits_after": 49,
      "megapixels": 2.15
    }
  },
  "id": 1
}

upload

auth required free

Upload an image or PDF with shareable link. Accepts base64-encoded content or a URL to fetch. Supports versioning (up to 50 per upload ID). No rendering — vhiz stores and serves the artifact as-is.

Parameters

Provide content or url, not both.

ParamTypeDescription
content string Base64-encoded file content. Provide content or url, not both.
url string URL to fetch content from. Provide url or content, not both.
format png · jpeg · pdf · webp Output format. Auto-detected from content magic bytes or URL extension if omitted.
title string Display name for share page.
id string Existing upload ID to append new version. Omit to create new upload. Caller may also supply a new ID following upload_ + 8 base62 convention — validated for format and uniqueness. format: upload_id

Result

id string
version integer
page string
Share page URL.
manifest string
Manifest URL for later retrieval.
artifact string
Direct artifact URL.
format string
width integer
Image width in pixels. Null for PDF.
height integer
Image height in pixels. Null for PDF.
size_bytes integer
resolved object
Echoed normalized params: { format }.
accounting object
Credits before/cost/after. Cost is always 0.
Errors (8)
CodeWhenMessage
-32602 missing content and url provide either content (base64) or url, not neither
upload takes {content: base64string} or {url: string}, plus optional format, title, id
-32602 both content and url provide either content or url, not both
-32602 invalid format invalid format: must be png, jpeg, pdf, or webp
-32602 invalid base64 content is not valid base64
-32602 format detection failed could not detect format from content. Specify format param explicitly.
-32602 size exceeded content exceeds 10 MB limit
-32602 fetch failed failed to fetch url: {reason}
-32602 upload not found upload not found: {id}
Upload a base64-encoded PNG
curl https://vhiz.dev/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer vhiz_YOUR_TOKEN' \
  -d '{
  "jsonrpc": "2.0",
  "method": "upload",
  "params": {
    "content": "iVBORw0KGgoAAAANSUhEU...",
    "title": "screenshot"
  },
  "id": 1
}'
{
  "jsonrpc": "2.0",
  "result": {
    "id": "upload_Rx4mN7wQ",
    "version": 1,
    "page": "https://vhiz.dev/upload_Rx4mN7wQ",
    "manifest": "https://vhiz.dev/upload_Rx4mN7wQ.json",
    "artifact": "https://vhiz.dev/upload_Rx4mN7wQ/v/1/artifact.png",
    "format": "png",
    "width": 1920,
    "height": 1080,
    "size_bytes": 284100,
    "resolved": {
      "format": "png"
    },
    "accounting": {
      "credits_before": 50,
      "cost": 0,
      "credits_after": 50
    }
  },
  "id": 1
}

List methods

list-renders

auth required free

List renders owned by the calling token, most recent first. Token-scoped: each token sees only its own renders.

Parameters

ParamTypeDescription
limit integer Max renders to return. default: 20 1–100
offset integer Number of renders to skip (for pagination). default: 0 min 0

Result

renders array
Each item:
id string
title string
created integer
Unix timestamp.
updated integer
Unix timestamp.
version_count integer
page string
Share page URL.
artifact string
Latest version artifact URL.
source string
Latest version source HTML URL.
total integer
Total renders owned by this token.
limit integer
offset integer
Errors (2)
CodeWhenMessage
-32602 invalid limit invalid limit: {n} (must be integer 1–100)
-32602 invalid offset invalid offset: {n} (must be non-negative integer)
List renders (default pagination)
curl https://vhiz.dev/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer vhiz_YOUR_TOKEN' \
  -d '{
  "jsonrpc": "2.0",
  "method": "list-renders",
  "params": {},
  "id": 1
}'
{
  "jsonrpc": "2.0",
  "result": {
    "renders": [
      {
        "id": "render_a1b2c3d4e5f60718",
        "title": "hello",
        "created": 1700000000,
        "updated": 1700000100,
        "version_count": 3,
        "page": "https://vhiz.dev/render_a1b2c3d4e5f60718",
        "artifact": "https://vhiz.dev/render_a1b2c3d4e5f60718/3.png",
        "source": "https://vhiz.dev/render_a1b2c3d4e5f60718/3/source.html"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0,
    "accounting": {
      "credits_before": 49,
      "cost": 0,
      "credits_after": 49
    }
  },
  "id": 1
}

list-captures

auth required free

List captures owned by the calling token, most recent first. Token-scoped: each token sees only its own captures.

Parameters

ParamTypeDescription
limit integer Max captures to return. default: 20 1–100
offset integer Number of captures to skip (for pagination). default: 0 min 0

Result

captures array
Each item:
id string
url string
Captured URL.
created integer
Unix timestamp.
format string
Output format (png, jpeg, pdf).
page string
Share page URL.
manifest string
Manifest URL.
artifacts object
Full artifacts object from capture: screenshots array, source.raw, extract.*
total integer
Total captures owned by this token.
limit integer
offset integer
Errors (2)
CodeWhenMessage
-32602 invalid limit invalid limit: {n} (must be integer 1–100)
-32602 invalid offset invalid offset: {n} (must be non-negative integer)
List captures (default pagination)
curl https://vhiz.dev/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer vhiz_YOUR_TOKEN' \
  -d '{
  "jsonrpc": "2.0",
  "method": "list-captures",
  "params": {},
  "id": 1
}'
{
  "jsonrpc": "2.0",
  "result": {
    "captures": [
      {
        "id": "capture_a1b2c3d4e5f60718",
        "url": "https://kottke.org",
        "created": 1700000000,
        "format": "png",
        "page": "https://vhiz.dev/capture_a1b2c3d4e5f60718",
        "manifest": "https://vhiz.dev/capture_a1b2c3d4e5f60718.json",
        "artifacts": {
          "screenshots": [
            "https://vhiz.dev/capture_a1b2c3d4e5f60718/output/screen1280x800@1x.png"
          ],
          "source": {
            "raw": "https://vhiz.dev/capture_a1b2c3d4e5f60718/source/raw.html"
          },
          "extract": {
            "dom": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/dom.html",
            "text": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/text.txt",
            "network": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/network.json",
            "assets": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/assets.json",
            "links": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/links.json",
            "head": "https://vhiz.dev/capture_a1b2c3d4e5f60718/extract/head.json"
          }
        }
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0,
    "accounting": {
      "credits_before": 49,
      "cost": 0,
      "credits_after": 49
    }
  },
  "id": 1
}

list-diagrams

auth required free

List diagrams owned by the calling token, most recent first. Token-scoped: each token sees only its own diagrams.

Parameters

ParamTypeDescription
limit integer Max diagrams to return. default: 20 1–100
offset integer Number of diagrams to skip (for pagination). default: 0 min 0

Result

diagrams array
Each item:
id string
title string
language string
Diagram language (e.g. mermaid).
created integer
Unix timestamp.
updated integer
Unix timestamp.
version_count integer
page string
Share page URL.
artifact string
Latest version artifact URL.
total integer
Total diagrams owned by this token.
limit integer
offset integer
Errors (2)
CodeWhenMessage
-32602 invalid limit invalid limit: {n} (must be integer 1–100)
-32602 invalid offset invalid offset: {n} (must be non-negative integer)
List diagrams (default pagination)
curl https://vhiz.dev/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer vhiz_YOUR_TOKEN' \
  -d '{
  "jsonrpc": "2.0",
  "method": "list-diagrams",
  "params": {},
  "id": 1
}'
{
  "jsonrpc": "2.0",
  "result": {
    "diagrams": [
      {
        "id": "diagram_Kp4wLn9R",
        "title": "deployment flow",
        "language": "mermaid",
        "created": 1700000000,
        "updated": 1700000100,
        "version_count": 2,
        "page": "https://vhiz.dev/diagram_Kp4wLn9R",
        "artifact": "https://vhiz.dev/diagram_Kp4wLn9R/v/2/screen1280x280@2x.png"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0,
    "accounting": {
      "credits_before": 49,
      "cost": 0,
      "credits_after": 49
    }
  },
  "id": 1
}

list-uploads

auth required free

List uploads owned by the calling token, most recent first. Token-scoped: each token sees only its own uploads.

Parameters

ParamTypeDescription
limit integer Max uploads to return. default: 20 1–100
offset integer Number of uploads to skip (for pagination). default: 0 min 0

Result

uploads array
Each item:
id string
title string
format string
Artifact format (png, jpeg, pdf, webp).
created integer
Unix timestamp.
updated integer
Unix timestamp.
version_count integer
page string
Share page URL.
artifact string
Latest version artifact URL.
total integer
Total uploads owned by this token.
limit integer
offset integer
Errors (2)
CodeWhenMessage
-32602 invalid limit invalid limit: {n} (must be integer 1–100)
-32602 invalid offset invalid offset: {n} (must be non-negative integer)
List uploads (default pagination)
curl https://vhiz.dev/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer vhiz_YOUR_TOKEN' \
  -d '{
  "jsonrpc": "2.0",
  "method": "list-uploads",
  "params": {},
  "id": 1
}'
{
  "jsonrpc": "2.0",
  "result": {
    "uploads": [
      {
        "id": "upload_Rx4mN7wQ",
        "title": "screenshot",
        "format": "png",
        "created": 1700000000,
        "updated": 1700000100,
        "version_count": 2,
        "page": "https://vhiz.dev/upload_Rx4mN7wQ",
        "artifact": "https://vhiz.dev/upload_Rx4mN7wQ/v/2/artifact.png"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0,
    "accounting": {
      "credits_before": 50,
      "cost": 0,
      "credits_after": 50
    }
  },
  "id": 1
}

Error Reference

Protocol-level error codes from JSON-RPC 2.0 and vhiz extensions.

Standard JSON-RPC

CodeNameMessageGuidance
-32700 parse_error Parse error JSON-RPC 2.0. Send {jsonrpc, method, params, id}. Try create-token for a free key.
-32600 invalid_request Invalid request One JSON-RPC object per request. No arrays (batch not supported).
-32601 method_not_found Method not found Available methods: create-token, check-token, list-renders, list-captures, list-diagrams, list-uploads, create-render, create-capture, create-diagram, upload, add-credits
-32602 invalid_params Invalid params
-32603 internal_error Internal error

Implementation-defined

CodeNameHTTPMessageGuidance
-32001 unauthorized 401 unauthorized Call create-token first — no auth needed, preloaded with 50 free credits (100 with email).
-32002 no_credits 402 out of credits Call add-credits to reload. Reduce dimensions/dpr to lower cost (≤4 MP = 1 credit), or use dry_run:true to preview cost.
-32003 pool_exhausted 503 all slots occupied All Chrome render/capture slots are in use. Retry after a few seconds.
-32004 engine_timeout 504 engine timed out Set timeout param to increase (max 60s).