Evidence in.
Decisions out.

What is JevLink?#

JevLink turns unstructured evidence into typed machine judgments and wraps the result in a verifiable service receipt. Jev evaluates the text. You define the question. JevLink adds an evidence check, applies request limits, signs the output and stores the record.

Your first request#

Run this from your terminal. Public Beta requests do not require an Authorization header. Send public text only: the input is stored in the receipt.

curl --fail-with-body https://jevlink.xyz/api/judgments \
  -H 'Content-Type: application/json' \
  --data '{
    "mode": "freeform",
    "prompt": "Does this order qualify for a refund? Policy: unused items within 30 days. Order: unopened, delivered 12 days ago."
  }'

A successful request returns 201 Created and a signed envelope. Decode its payload to inspect the fields; verify its signature before treating it as an authentic JevLink record.

JavaScript / Node.js

Download the verification helper into your project, save the example as judgment.mjs, then run node judgment.mjs. Node.js 20 or newer; no packages required.

// Node.js 20+. Save as judgment.mjs.
// Download verify-receipt.mjs below into the same directory.
import { verifyReceipt } from './verify-receipt.mjs';

const response = await fetch('https://jevlink.xyz/api/judgments', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mode: 'freeform',
    prompt: 'Does this order qualify for a refund? Policy: unused items within 30 days. Order: unopened, delivered 12 days ago.'
  }),
  signal: AbortSignal.timeout(35000)
});
const body = await response.json();
if (!response.ok) {
  throw new Error(
    response.status + ': ' + body.error +
    ' (Retry-After: ' + (response.headers.get('retry-after') ?? 'none') + ')'
  );
}
const receipt = await verifyReceipt(body.receipt);
console.log(receipt.id, receipt.model, receipt.durationMs);
console.log(receipt.answers, receipt.labels);
// Consume a concrete answer only when the evidence is sufficient.
const ready = receipt.answers.readiness.choice === 'answerable';
const choice = receipt.answers.judgment.choice;
console.log(ready && choice !== 'unclear' ? receipt.labels[choice] : 'Review context');
console.log('https://jevlink.xyz/explorer?id=' + receipt.id);

# Python 3.10+. Standard library only.
import base64, json, urllib.request, urllib.error

data = {
    "mode": "freeform",
    "prompt": "Does this order qualify for a refund? Policy: unused items within 30 days. Order: unopened, delivered 12 days ago."
}
request = urllib.request.Request(
    "https://jevlink.xyz/api/judgments",
    data=json.dumps(data).encode("utf-8"),
    headers={"Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=35) as response:
        envelope = json.load(response)["receipt"]
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode()}") from None

# Inspection only: decoding is NOT signature verification.
payload = envelope["payload"]
receipt = json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
print(receipt["answers"], receipt["labels"])
print("Verify in Explorer: https://jevlink.xyz/explorer?id=" + receipt["id"])

Create a judgment#

Content-Type must be application/json. Unknown fields are rejected. The total request body must not exceed 20,000 bytes.

Free input, structured output

Jev evaluates your question and an evidence-readiness check in one request. It selects from typed answer options rather than generating chat responses. Without custom options, ask a yes/no question or provide a claim to assess. For routing, add options such as Billing, Access and Performance.

There is no topic whitelist or minimum beyond one non-whitespace character. A live-price query is accepted in freeform mode and evaluated by Jev, but no price feed or web search is attached. Expect needs_live_data when current evidence is missing. Pasted URLs are text, not fetched pages.

// HTTP 201 — shape only; placeholders are not a valid receipt.
{
  "receipt": {
    "payload": "<base64url-encoded JSON>",
    "signature": "<base64url-encoded ECDSA signature>",
    "keyId": "jevlink-<key fingerprint>",
    "algorithm": "ECDSA-P256-SHA256"
  }
}

Read the signals#

For v3, read answers.judgment and answers.readiness. Both contain the actual Jev choice, full probabilities and confidence. Resolve the answer label through labels[answers.judgment.choice].

The website applies a simple presentation rule: only readiness = answerable with judgment ≠ unclear produces a signal. Otherwise it displays a context check. The unmodified Jev answers remain in the receipt. This is not a safety guarantee or an executed policy.

// Selected fields after verification; illustrative values.
// The actual payload also includes inputHash, questions and usage.
{
  "schema": "jevlink.receipt.v3",
  "id": "<UUID>",
  "issuedAt": "<UTC timestamp>",
  "issuer": "JevLink",
  "model": "jev-1.13.0",
  "provider": "TypeSafe Direct",
  "method": "freeform-judgment-v1",
  "input": { "prompt": "<your question and context>" },
  "labels": { "yes": "Yes", "no": "No", "unclear": "Undetermined" },
  "answers": {
    "judgment": { "choice": "yes", "probabilities": { "yes": 0.98, "no": 0.01, "unclear": 0.01 }, "confidence": 0.98 },
    "readiness": { "choice": "answerable", "probabilities": { "answerable": 0.97, "needs_context": 0.01, "needs_live_data": 0.01, "needs_options": 0.01 }, "confidence": 0.97 }
  },
  "durationMs": 500
}

Announcement mode · v2 compatibility

These four fixed signals apply only to the legacy announcement method, not to freeform questions.

Each signal contains choice and probabilities. New direct responses contain the full choice distribution. Legacy receipts can contain null probabilities; handle them as unknown, not zero risk.

Receipts & fields#

The outer envelope contains payload, signature, keyId and algorithm. Both the payload and signature are unpadded base64url. The payload decodes to UTF-8 JSON.

The browser separately measures the full request round trip. Neither timing is blockchain settlement time or a latency guarantee. Consumers should validate the schema and fields they use, and reject unsupported versions.

Verify a receipt#

The response contains keyId, publicKey (a P-256 JSON Web Key) and algorithm. Without a keyId, it returns the current signing key. Pass the envelope’s keyId so older records use the correct key. An unknown key returns 404.

1. Obtain the public key from the trusted JevLink origin, or use a previously trusted copy. Never trust a key embedded in a receipt or a URL supplied by the receipt.
2. Check that the keyId and algorithm match. The algorithm is ECDSA P-256 with SHA-256.
3. Verify the decoded signature against the UTF-8 bytes of the original base64url payload string. Do not verify against decoded JSON or reserialized JSON. The signature uses the 64-byte IEEE P1363 r‖s format, not DER.
4. Decode the payload. Compute SHA-256 over UTF-8 JSON.stringify(receipt.input) and compare its lowercase hex digest to inputHash. Preserve key order and JavaScript JSON serialization semantics.
5. Validate the supported schema, method, expected input and options, field types and your own freshness policy before consuming the signal.

The downloadable Node.js helper implements signature and input-hash verification and basic schema checks. Your application must still validate the fields it consumes and decide how old a receipt may be. For offline verification, retain a trusted public key and the original envelope.

To verify without writing code, open Explorer, enter the receipt ID or import its JSON, then select Verify receipt.

Retrieve a record#

Use the UUID inside the decoded payload. This returns the original { "receipt": envelope }, not a new model evaluation. Invalid UUIDs return 400; records not found return 404. Receipt retrieval does not consume the inference quota.

// Node.js 20+. Use an ID returned by your first request.
import { verifyReceipt } from './verify-receipt.mjs';
const id = process.argv[2];
if (!id) throw new Error('Usage: node inspect.mjs <receipt-id>');
const response = await fetch(
  'https://jevlink.xyz/api/receipts/' + encodeURIComponent(id)
);
if (!response.ok) throw new Error('Receipt lookup failed: ' + response.status);
const body = await response.json();
const receipt = await verifyReceipt(body.receipt);
console.log(receipt);

Share a record with https://jevlink.xyz/explorer?id={id}. Anyone with that link or ID can read the input and output. There is no public receipt-list endpoint. All API responses specify Cache-Control: no-store; save envelopes in your own application when you need a durable independent copy. No retention-duration guarantee or deletion API is published in this Beta.

Connect your application#

Call JevLink from your backend, scheduled job or terminal. The public API does not enable cross-origin browser access; a third-party browser should call your server, which then calls JevLink. Never embed TypeSafe’s provider key in your frontend or send it to this public endpoint.

Any decision, your policy

Ask whether an order satisfies a refund policy, whether a message exhibits phishing indicators, or which team should handle an incident. Supply the evidence and options, then verify the record. Your application defines any action and should route undetermined or low-confidence results for review.

A venue-risk control · announcement mode

Ingest a public venue announcement, request the four signals, verify the record, and route the result to an operator alert or an application-controlled hold. Preserve the receipt ID beside the resulting decision for review.

The announcement receipt viewer’s Vault Guard applies this illustrative policy: a qualifying adverse signal at 90% or above yields PAUSED; otherwise, all four explicit clear signals at 90% or above yield NO HOLD TRIGGER; any remaining case yields REVIEW.

// Apply only AFTER signature, schema and freshness checks.
const ids = ['withdrawals', 'trading', 'security', 'losses'];
const signals = receipt.signals;
const threshold = receipt.policy.threshold;
const adverse = ids.some(id => {
  const answer = signals[id];
  const trigger = id === 'losses' ? 'confirmed' : 'yes';
  return answer.choice === trigger &&
    (answer.probabilities?.[trigger] ?? 0) >= threshold;
});
const explicitClear = ids.every(id => {
  const answer = signals[id];
  const clear = id === 'losses' ? 'explicitly_denied' : 'no';
  return answer.choice === clear &&
    (answer.probabilities?.[clear] ?? 0) >= threshold;
});
const decision = adverse ? 'PAUSED' : explicitClear ? 'NO HOLD TRIGGER' : 'REVIEW';
console.log(decision); // Your application decides what to do; no transaction is sent.

No hold trigger is not a safety clearance. Never automatically clear an earlier hold just because a later announcement is silent or reassuring. The API does not execute the policy, call smart contracts or move funds.

Other practical integrations

• Exchange monitoring: route withdrawal and trading disruptions to separate incident channels.
• Portfolio operations: flag new exposure to an affected venue for human approval, with the original announcement attached.
• Incident triage: distinguish confirmed fund losses from ongoing investigations, and queue unclear reports for follow-up.

These are consumer-side integration patterns, not additional live endpoints. Event ingestion, source authentication, stale-data checks, deduplication and any action execution belong to your application.

Access, limits & privacy#

Do not submit secrets, private account data or personal information. Signature validity does not imply freshness: compare issuedAt with your own expiry window and verify that the original announcement is still relevant.

Errors & recovery#

Errors return JSON with an error string. In legacy modes only, unsupported price-lookups also include code: "unsupported_input". Status codes are the reliable branch; do not parse English message text as a stable API contract.

{
  "error": "Please wait a minute before running another judgment."
}

Retry deliberately

There is no idempotency-key support. Every repeated POST can create a new inference and receipt and consume quota. A timeout does not prove the first request failed. Use a bounded retry budget with backoff and jitter, and deduplicate evidence in your application. Do not retry invalid input or keep polling a depleted daily quota.

Store the receipt before triggering downstream work. If verification, freshness or schema checks fail, stop the action and surface the failure to an operator.