Vouch API

Deterministic preflight governance for AI agent plans. One API call between plan proposal and downstream execution.

What Vouch is

Vouch is a deterministic preflight governance layer for AI agent plans. It evaluates plans before they reach a downstream LLM or tool execution layer.

Your system makes one API call to Vouch. Vouch returns a verdict, explicit release semantics, guidance, and savings context: ACCEPTED, CAUTION, or BLOCKED.

Vouch does not modify the plan. It does not call the downstream model. It evaluates and returns.

Where it sits

Authentication

Every request to POST /api/v1/vouch requires an API key. Pass it as a header:

x-api-key: YOUR_API_KEY

Your API key is issued by us during onboarding. If you need a key rotated or reissued, contact us directly.

Request format

Endpoint: POST /api/v1/vouch
Content-Type: application/json
Max body: 512 KB

Required fields

Each step should include:

Optional metadata

Include these fields to activate tenant-scoped savings and richer evaluation:

Quick start

Your first successful call in under a minute. Replace YOUR_VOUCH_ENDPOINT and YOUR_API_KEY with the values from your Account page.

Copycurl -X POST https://YOUR_VOUCH_ENDPOINT/api/v1/vouch \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "surface": "vouch",
    "tenant": "your_tenant",
    "downstream_model": "gpt-4o",
    "description": "Rotate the API signing key for the payments service",
    "steps": [
      {
        "action": "generate new signing key",
        "target": "payments-service API key",
        "destination": "secrets manager"
      },
      {
        "action": "update key reference in config",
        "target": "payments-service config",
        "destination": "internal config store"
      },
      {
        "action": "revoke old key",
        "target": "previous payments-service API key",
        "destination": "secrets manager"
      }
    ]
  }'

Response format

Every response returns this shape:

{
  "verdict": "ACCEPTED",
  "release_status": "release",
  "send_to_downstream": true,
  "review_required": false,
  "verification_eligible": false,
  "guidance": null,
  "estimated_savings": "$0.04",
  "rolling_7d_savings": "$12.48",
  "request_id": "v-a1b2c3d4e5f60718"
}

CAUTION example

{
  "verdict": "CAUTION",
  "release_status": "review",
  "send_to_downstream": true,
  "review_required": true,
  "verification_eligible": true,
  "guidance": "This plan modifies or bypasses a security control. Security control changes require documented approval. Propose through the governance process.",
  "estimated_savings": "$0.04",
  "rolling_7d_savings": "$12.48",
  "request_id": "v-9f8e7d6c5b4a3021"
}

BLOCKED example

{
  "verdict": "BLOCKED",
  "release_status": "hold",
  "send_to_downstream": false,
  "review_required": false,
  "verification_eligible": false,
  "guidance": "This plan creates or modifies identity or access outside the standard workflow. Identity and access changes require an approved provisioning workflow with audit trail.",
  "estimated_savings": "$0.04",
  "rolling_7d_savings": "$12.52",
  "request_id": "v-1a2b3c4d5e6f7890"
}

Verdict meanings

Integration pattern

The recommended integration point is your backend or orchestrator, not a model-adjacent surface.

Two-checkpoint pattern

If you want two governance checkpoints, the second clean point is before tool execution -- after the model returns a tool-use action, evaluate that action as a new plan before executing it. Both checkpoints use the same endpoint.

Python & Node integration

Python

Copyimport requests

VOUCH_ENDPOINT = "https://YOUR_VOUCH_ENDPOINT"
VOUCH_API_KEY  = "YOUR_API_KEY"

def evaluate_plan(description, steps, tenant="default", model="gpt-4o"):
    response = requests.post(
        f"{VOUCH_ENDPOINT}/api/v1/vouch",
        headers={
            "Content-Type": "application/json",
            "x-api-key": VOUCH_API_KEY,
        },
        json={
            "surface": "vouch",
            "tenant": tenant,
            "downstream_model": model,
            "description": description,
            "steps": steps,
        },
        timeout=5,
    )
    result = response.json()

    if result["verdict"] == "ACCEPTED":
        # Proceed to downstream model
        return send_to_downstream(description, steps)
    elif result["verdict"] == "CAUTION":
        # Log guidance, apply your review policy
        log_review(result["guidance"], result["request_id"])
        return None
    else:
        # BLOCKED — stop, do not execute
        log_block(result["guidance"], result["request_id"])
        return None

Node.js

Copyconst VOUCH_ENDPOINT = "https://YOUR_VOUCH_ENDPOINT";
const VOUCH_API_KEY  = "YOUR_API_KEY";

async function evaluatePlan(description, steps, tenant = "default", model = "gpt-4o") {
  const res = await fetch(`${VOUCH_ENDPOINT}/api/v1/vouch`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": VOUCH_API_KEY,
    },
    body: JSON.stringify({
      surface: "vouch",
      tenant,
      downstream_model: model,
      description,
      steps,
    }),
  });

  const result = await res.json();

  if (result.verdict === "ACCEPTED") {
    // Proceed to downstream model
    return sendToDownstream(description, steps);
  } else if (result.verdict === "CAUTION") {
    // Log guidance, apply your review policy
    logReview(result.guidance, result.request_id);
    return null;
  } else {
    // BLOCKED — stop, do not execute
    logBlock(result.guidance, result.request_id);
    return null;
  }
}

Savings fields

estimated_savings is the modeled cost of the downstream LLM call this evaluation replaced or avoided. It uses provisional model-class cost defaults based on the downstream_model you provide.

rolling_7d_savings is your tenant's trailing 7-day total of avoided downstream costs.

The full cost story combines avoided LLM calls, avoided loop churn, avoided operator time, and avoided security incidents. Token savings alone are real but modest on cheap models. The structural value -- one blocked credential exfiltration is worth more than a year of token savings -- is where governance earns its keep.

Error responses

Fail-closed behavior

Vouch fails closed. If the pipeline encounters an internal error, the response is a 500 with an error payload — it does not silently return ACCEPTED.

Copy# If Vouch is unreachable or returns an error,
# do NOT proceed with the plan.
if response.status_code != 200:
    log_error("Vouch unavailable", response.status_code)
    return block_plan("governance layer unreachable")

# Only proceed on an explicit ACCEPTED verdict
result = response.json()
if result["verdict"] != "ACCEPTED":
    return handle_non_accepted(result)

Vouch does not fail open. Plans are never silently approved. If you cannot reach Vouch, the correct behavior is to hold the plan until governance is available.

Health check

GET /api/v1/status

Returns {"status": "ok"} when the service is running. No authentication required.

Trial and paid

Trial and paid both run the full Vouch pipeline. Trial is not a sandbox and paid is not a different detector. What changes is the deployment posture and operating model.

Support

For onboarding help, integration questions, or to discuss a dedicated managed instance:

Email: jordan@atlaswithiris.com

Include your tenant name in the subject line for faster routing.