BASE URL / HTTPS://API.VERAHELM.COM

Compact requests. Stable codes. Hard boundaries.

API version v1 exposes thirteen live operations through POST /v1/analyze; five stable operation-specific paths remain compatible. Every body is strict JSON, every result is validated code-only output, and customer inputs and full outputs are discarded after the active request.

OPEN OPENAPI 3.1 ↗ PIPELINE QUICKSTART ↓ GATE PROFILE REFERENCE ↓ PUBLIC VERIFIER ON GITHUB ↗ INSTALL GITHUB ACTION ↗ CREATE FREE KEY →

BASE URLhttps://api.verahelm.com

VERSIONv1

FORMATSTRICT JSON

STATUSVIEW LIVE ↗

Documentation controls ready.

01 / REQUEST CONTRACT

Authentication, idempotency, and limits.

Authentication

Send Authorization: Bearer vh_live_… from a server-side secret manager. Free keys use vh_test_, selected flagship endpoint scopes, low rate and concurrency limits, a calendar-month quota, and a non-production result marker. Never put a key in a URL, query string, cookie, browser JavaScript, storage, analytics, email, log, screenshot, or support export.

Headers and content

Each evaluation requires Content-Type: application/json, Accept: application/json, and a unique Idempotency-Key of 16–128 characters matching [A-Za-z0-9_.:-]. Unknown content types, fields, methods, hosts, query strings, browser origins/cookies, and oversized bodies are rejected before execution. Multipart, streaming, binary, base64 files, archives, URLs, webhooks, and uploads are unsupported.

Endpoint map

GET/v1/healthPUBLIC

Aggregate readiness only.

POST/v1/analyzeAPI KEY

Unified thirteen-profile contract.

GET/v1/decision-envelope-keys/{key_id}PUBLIC

Public signature-verification key.

GET/v1/decision-envelopes/{envelope_id}/statusAPI KEY

Signed current lifecycle state.

POST/v1/decision-envelopes/{envelope_id}/revokeAPI KEY

Revoke an active envelope.

Five operation-specific evaluation paths remain supported for compatibility. New integrations should use POST /v1/analyze.

Rates and evaluation units

PLAN	PRICE / PERIOD UNITS	HARD REQUEST LIMITS	KEY / PAYLOAD / PROCESSING
Free	$0 · 30 units/calendar month · 6/day · payment-method verification required; no charge or subscription	2 requests/10 seconds · 5/minute · concurrency 1	1 restricted non-production key · 8,192 bytes · 5 seconds
Developer	$49/month · 300 units · 30/day	5 requests/10 seconds · 30/minute · concurrency 2	1 live key · 12,288 bytes · 6 seconds
Professional	$149/month · 1,500 units · 150/day	13 requests/10 seconds · 90/minute · concurrency 5	5 live keys · 16,384 bytes · 8 seconds · metadata export

Unused units expire at billing-period end. There is no rollover, automatic overage, or overage billing. Email support is best effort and has no response-time SLA. A unit is reserved atomically, finalized once on a successful validated result, and released after validation, policy, processing, timeout, or service failure. Identical idempotent retries within 24 hours replay the deterministic result without a second charge.

GATE PROFILE	BASE UNITS
`decision_signal`, `claim_triage`, `evidence_sufficiency_map`, `decision_receipt_retest_map`	1
`pairwise_signal`, `boundary_stress_signal`, `next_test_value_map`, `autonomy_budget_gate`, `failure_coverage_map`	2
`pipeline_improvement_map`, `migration_readiness_map`, `mcp_admission_map`, `agent_change_gate`	3

Each additional started 4,096-byte request block adds one unit. boundary_stress_signal also adds one unit for each sample after the first. Example: 100 three-unit pull-request or agent-change gates use all 300 Developer units when each request is at most 4,096 bytes.

Timeout and retry

Processing limits are 6 seconds for Developer and 8 seconds for Professional. Use a safe retry only for transport interruption, 429 after Retry-After, or 503, with the same idempotency key and identical body. Never retry validation, authentication, entitlement, scope, policy, or restricted-data failures. Identical completed requests replay for 24 hours by deterministic recomputation; Verahelm retains only idempotency and usage metadata, not request or result content.

Signed Decision Envelopes

Add decision_context to POST /v1/analyze to bind the result to an exact subject and SHA-256 version, change scope, evidence digests, customer-confirmed authority, conditions, and an expiry from 5 minutes to 7 days. The response includes an Ed25519-signed Decision Envelope. A favorable gate maps to pass; every other status maps to blocked. Mandatory conditions prohibit consequential use and production authorization.

Retrieve the public JWK from GET /v1/decision-envelope-keys/{key_id}. Authenticated customers can retrieve signed current state from GET /v1/decision-envelopes/{envelope_id}/status, revoke an active envelope with POST /v1/decision-envelopes/{envelope_id}/revoke, or issue a replacement with supersedes. Verahelm retains lifecycle and keyed-digest metadata only; it does not retain the subject, evidence, request, or full result.

Decision Envelope binding fields and constraints are defined in the OpenAPI contract. Binding examples are intentionally excluded.

02 / OPERATIONS

Thirteen live schemas.

Select by workflow. Expand a profile for its public input and output contract; use OpenAPI for exact types, enums, and bounds.

FILTER PROFILES 13 profiles

CHANGE AUTHORIZATION

Gate a proposed change.

POSTagent_change_gate3 units

Submit Agent-origin state, protected-policy source, change categories, exact-head evidence booleans, and bounded reviewer counts.

Receive Gate state, blocking codes, required actions, and eligibility for a separately verified trusted passport.

POSTmigration_readiness_map3 units

Submit Migration/workload codes, bounded baseline/candidate checks, hard gates, readiness booleans, and non-consequential context.

Receive Per-metric states, evidence gaps, required tests, ordered rollout codes, and bounded readiness state.

POSTmcp_admission_map3 units

Submit Closed publisher, release, capability, authorization, data, runtime, operational, and buyer-policy states.

Receive Admission state, evidence gaps, restrictions, revisit triggers, and passport eligibility.

DECISION LIFECYCLE

Keep prior decisions current.

POSTdecision_receipt_retest_map1 unit

Submit Record state, evidence age, prior outcome, controlled change signals, and evidence-control booleans.

Receive Validity or retest state, invalidating changes, required tests, revisit triggers, and reuse status.

POSTfailure_coverage_map2 units

Submit Bounded failure classes with known, tested, and unresolved counts, severity, and coverage controls.

Receive Coverage and risk bands, gap codes, required tests, revisit triggers, and readiness.

POSTautonomy_budget_gate2 units

Submit Action class, blast radius, data scope, reversibility, authorization state, and bounded controls.

Receive Autonomy mode, budget band, control gaps, required actions, and revisit triggers.

EVIDENCE PLANNING

Find the next required work.

POSTevidence_sufficiency_map1 unit

Submit Disjoint available, missing, and contradictory evidence codes plus dependency codes.

Receive Coverage, gap, contradiction, dependency codes, and readiness state.

POSTnext_test_value_map2 units

Submit Bounded non-identifying test labels with impact, uncertainty, detection, effort, time, prerequisite, and independent-check bands.

Receive Deterministic rank, eligibility, priority bands, reason codes, and one recommended label—without a disclosed internal score.

POSTpipeline_improvement_map3 units

Submit Bounded stage/problem codes, exact constraints, and optional prior-result or configuration-change codes.

Receive Prioritized coded improvements, change-risk codes, and required release tests.

BOUNDED SIGNALS

Classify narrow evidence.

POSTdecision_signal1 unit

Submit Category, short description, bounded metrics, observation codes, and fixed non-consequential context.

Receive Signal state, flags, boundary notes, next test, confidence, and manual route.

POSTpairwise_signal2 units

Submit Exactly two non-identifying candidate labels with the same bounded metric conditions.

Receive Directional result plus material, failure-pattern, and unresolved-boundary codes.

POSTclaim_triage1 unit

Submit One short claim plus a category, count, and boolean evidence summary.

Receive Triage state, evidence gaps, boundary conditions, next test, and manual route.

POSTboundary_stress_signal2+ units

Submit One item, bounded metrics, and a server-bounded sample count.

Receive Stable, sensitive, unstable, or insufficient state with sanitized codes.

The complete closed enums, lengths, numeric bounds, response variants, and error contract are in openapi.json. The service rejects unexpected fields and does not fetch URLs, execute code, render HTML, inspect files, or independently verify caller assertions.

03 / QUICKSTART

From contract to a fail-closed request.

Choose a profile

Start with the workflow groups above. Confirm the exact request schema in OpenAPI.

Validate locally

Reject unknown fields and prohibited content before any network request.

Send server-side

Load the key from a secret manager and use one unique idempotency key.

Verify and enforce

Check the response contract and any signed lifecycle state; fail closed on uncertainty.

GET

Check aggregate readiness

/v1/health

curl --fail-with-body --silent --show-error \
  https://api.verahelm.com/v1/health \
  -H 'Accept: application/json'

GET

Download the exact contract

/openapi.json

curl --fail --silent --show-error \
  https://www.verahelm.com/openapi.json \
  --output openapi.json

AUTHENTICATED TRANSPORT

Submit a locally validated request file.

POST /v1/analyze

curl --fail-with-body --silent --show-error \
  -X POST https://api.verahelm.com/v1/analyze \
  -H "Authorization: Bearer $VERAHELM_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-binary @request.json

import { readFile } from "node:fs/promises";

const body = await readFile("request.json", "utf8");
const response = await fetch("https://api.verahelm.com/v1/analyze", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.VERAHELM_API_KEY}`,
    "content-type": "application/json",
    "idempotency-key": process.env.IDEMPOTENCY_KEY
  },
  body
});
const requestId = response.headers.get("x-request-id");
if (!response.ok) throw new Error(`Verahelm ${response.status}; ${requestId ?? "no request id"}`);
const result = await response.json();
if (result?.api_version !== "v1") throw new Error("unsupported response");
// Validate the complete result against OpenAPI before use; do not log it.

import os
from pathlib import Path
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request = Request(
    "https://api.verahelm.com/v1/analyze",
    data=Path("request.json").read_bytes(),
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['VERAHELM_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": os.environ["IDEMPOTENCY_KEY"],
    },
)
try:
    with urlopen(request, timeout=10) as response:
        result = response.read()
except HTTPError as error:
    raise SystemExit(f"Verahelm {error.code}; request failed closed")
# Validate result against OpenAPI before use; do not log it.

04 / INTEGRATION BOUNDARY

Measure locally. Submit the minimum. Verify the signed record.

Keep source evidence under customer control. Submit only permitted bounded summaries through the documented hosted contract, bind any returned Decision Envelope to the exact subject and version, and verify its signature and current lifecycle state offline.

Worked payload/result pairs are intentionally excluded.
A gate result is decision support, not certification, safety assurance, compliance approval, or deployment authority.
Customer authorization and independent controls remain required.

05 / GATE PROFILE REFERENCE

One hosted contract, grouped by customer workflow.

Pull request or agent changeagent_change_gate

Tool or MCP admissionmcp_admission_map

Migration rolloutmigration_readiness_map

Prior-decision reusedecision_receipt_retest_map

Failure-case readinessfailure_coverage_map

Complete request and decision-output pairs remain intentionally excluded. Use the OpenAPI contract for required types, limits, and response fields.

06 / INTEGRATION SEQUENCE

Keep evidence local and verification independent.

Validate customer-controlled evidence locally.
Send only the minimum permitted bounded summary with an idempotency key.
Reject transport, schema, authorization, or lifecycle failures closed.
Verify any signed envelope and signed lifecycle status offline.
Apply customer authority and independent release controls.

07 / RESPONSE + ERRORS

Stable, versioned, machine-readable JSON.

Complete decision-output examples are not published. The versioned response contract and coarse error codes remain defined in OpenAPI.

Errors use {"api_version":"v1","id":"req_…","error":{"code":"…","status":…}}. Expect safe HTTP 400, 401, 403, 404, 405, 409, 413, 415, 422, 429, or 503. Every response includes X-Request-ID and Cache-Control: no-store, max-age=0. Responses never include stack traces, provider bodies, customer enumeration, prompts, reasoning, formulas, weights, heuristics, feature contributions, proprietary intermediate values, or debug data.

2XXACCEPT

Validate the documented response schema before use.

400 / 409 / 413 / 415 / 422FIX REQUEST

Do not retry unchanged input.

401 / 403 / 404 / 405FIX ACCESS

Do not retry until authorization or routing is corrected.

429WAIT

Honor Retry-After; reuse the identical body and idempotency key.

503RETRY SAFELY

Back off; reuse the identical body and idempotency key.

Version glossary

VERSION	WHERE IT APPEARS	WHAT IT IDENTIFIES
Path version	The `/v1` segment of every endpoint path and the `api_version` field of every response.	The wire contract generation; currently `v1`.
OpenAPI document version	`info.version` in openapi.json; currently `1.4.0`.	The revision of the published OpenAPI document itself.
Response schema version	The `schema_version` field of every evaluation response; currently `VH_PUBLIC_RESULT_V1`.	The public response envelope layout.
Code-set version	The `code_set_version` field of every evaluation response; currently `2026-07-26-US-NC-B2B-v2`.	The closed public enum code set used in the result.
Ruleset version	The `ruleset_version` field of every evaluation response.	An opaque compatibility identifier for the hosted result.
Receipt/digest version	The `request_digest` and `result_digest` fields of every evaluation response.	Per-evaluation keyed digests of the canonical request and the result code envelope; they identify one evaluation, not a contract revision.

Compatibility policy: within path version v1, contract changes are additive only — new enum codes or new optional fields. A breaking change ships under a new path version with the deprecation notice policy in Section 09.

08 / DATA + SERVICE BOUNDARY

Zero persistent API-payload retention by default.

Request content exists only in active-request memory. Verahelm does not write API inputs or full outputs to persistent databases, caches, queues, analytics, ordinary logs, or searchable history and cannot recover them. Usage records contain only customer/key references, operation, units, time, result status, latency, provider cost, token total, and error code.

The API accepts contract-bounded summaries and returns documented code-only outputs. Verahelm's private decision engine is not published. Public clients do not receive private instructions, thresholds, scores, intermediate values, derivations, or method source.

09 / LIFECYCLE

Versioning, changes, and escalation.

Breaking contract changes receive a new API version. Compatible enum additions or limits may be announced in the changelog before activation. A supported version receives a published deprecation date and at least 89 days' notice unless immediate suspension is necessary for law, security, provider loss, or abuse. Current changelog: v1 / 2026-07-22 — initial bounded contract. 2026-07-26 — contract expanded to the current thirteen documented operations.

To escalate, use the authenticated customer portal. Only the public run reference, operation/result/reason codes, suggested service, and exact explicitly approved non-confidential summary are transferred. The original API input is not available to a reviewer.

Status: status.verahelm.com. Security: security@verahelm.com. Privacy: privacy@verahelm.com. Support: support@verahelm.com. Never send secrets or customer content by email.