13.3 / Technical insight

API SLA Verification: Evidence, Checks and Receipts

API SLA verification turns service-level promises into explicit measurements that another system can inspect and recompute.

Project statusLive public MVPPVTY tokenLive on Solana
Scope:A deterministic SLA result is only as reliable as its measurement source and observation window. It is evidence processing, not independent monitoring unless a separate monitor supplied the evidence.

By PactVerity · Updated

How do you verify an API SLA?

Agree the rule and observation window, preserve the original measurements, then evaluate each expected sample. A sampled result describes the evidence collected—not continuous uptime. Missing measurements must remain unknown rather than being counted as passes.

For the example policy below: provisional credit = invoice × min(failed windows × credit rate, cap), rounded down to whole cents. A $1,000 invoice with two failed windows, 1% per failure and a 10% cap produces $20. Your contract may use different rules.

PASS
A usable observation meets the configured rule.
FAIL
A usable observation breaches the configured rule.
UNKNOWN
The sample is missing, unusable or cannot establish the result. It is neither a pass nor automatic proof of downtime.
EXCLUDED
The contract explicitly excludes the window, such as agreed maintenance; retain the reason.

Run the six-window worked example and download its offline script. The sample includes two unknown windows, so its $20 output is a provisional claim with incomplete coverage, not an automatic refund.

01 / Contract

Translate prose into measurable conditions.

An SLA often combines technical targets, exclusions, maintenance windows and commercial remedies. Software cannot evaluate that prose safely unless the relevant conditions are represented as explicit fields. Begin with a narrow service definition, measurement period, units and threshold direction. A maximum latency rule is different from a minimum uptime rule, and both need an agreed aggregation method.

Identifiers also matter. The verifier should know which endpoint, region, plan and version the evidence describes. Without that context, a passing measurement from one service could be attached to a different agreement. Canonical agreement and provider references reduce that ambiguity.

  • Define latency as a percentile and time window, not an isolated best result.
  • Represent uptime in an agreed unit such as basis points and state exclusions separately.
  • Record freshness relative to an observation timestamp.
  • Commit expected and observed outputs with a documented hashing method when exact content matters.

02 / Evidence

Capture measurements with provenance.

A number without provenance is difficult to challenge or defend. Evidence should record when it was observed, the measurement source, the target being measured and any transformation applied before evaluation. If a third-party monitor, provider signature or system-of-record response exists, preserve that reference alongside the normalised value.

Missing and stale evidence require explicit treatment. A freshness threshold should fail or hold a decision when the observation is too old. A malformed value should not silently become zero. These rules prevent evidence-pipeline problems from being misreported as successful delivery.

03 / Evaluation

Use deterministic rules for repeatable outcomes.

The evaluation engine should expose each check, its expected threshold, the observed value and the comparison result. Versioning is essential: when a rule changes, the receipt must continue to identify the earlier logic so historical decisions remain reproducible.

A cryptographic digest binds the canonical agreement, evidence, check results and engine version. Recomputing that digest later detects alteration, while repeating the comparisons confirms that the recorded outcome follows from the supplied inputs. This is stronger than exporting a PDF report that cannot be mechanically re-evaluated.

04 / Worked freshness example

Detect stale API data without mistaking retrieval time for observation time.

Consider a synthetic API observation stamped 2026-09-27T12:00:00Z, evaluated at 2026-09-27T12:02:00Z. Its age is 120 seconds. A policy allowing evidence no older than 60 seconds must fail that freshness check, even if latency and uptime pass. This is an arithmetic illustration, not a report of a customer incident or an independent measurement.

Repeat the comparison with an observation stamped 12:01:30Z: its age is 30 seconds, within the same limit. Preserve the original observation time; fetching an old response at 12:02:00Z does not make its contents fresh. Reject an invalid timestamp and investigate a future timestamp instead of silently converting either into age zero.

Document where the clock and observation come from, how clock skew is bounded, and whether your policy uses an inclusive boundary. For a rule age <= 60 seconds, exactly 60 seconds passes and 61 seconds fails. If your implementation uses different semantics, publish that rule rather than implying compatibility. A passing calculation still cannot prove that the source supplied an honest timestamp.

  • Stale fixture: 120 seconds old; 60-second limit; expected FAIL.
  • Fresh fixture: 30 seconds old; 60-second limit; expected PASS.
  • Boundary fixture: 60 seconds old; inclusive 60-second limit; expected PASS.
  • Invalid and future timestamps: explicit error or documented review outcome, never an invented successful observation.

05 / Reproduce a credit

Six observations, two failures, a capped provisional claim.

The Evidence Gateway synthetic walkthrough uses a $1,000 invoice, 1% credit per failed window and a 10% cap. One fast 200 response passes; a 503 and a slow 200 fail; a timeout and a missing sample remain unknown; one maintenance window is excluded. Two failures produce a $20 provisional claim, not a refund. Coverage is incomplete because two windows are unknown.

Open the Gateway worked example to download an offline Node.js script and evaluator. It asserts the expected counts and credit, checks the lower-cap case and rejects altered signed evidence—even after an attacker recomputes the digest. All observations are fictional; the script uses an ephemeral demonstration key, makes no requests and moves no funds.

06 / Remedies

Keep verification separate from settlement.

An SLA result can inform a credit, refund or dispute process, but it should not be confused with executing that remedy. Payment movement introduces authorisation, legal and operational requirements beyond measurement. A safe architecture states whether it is only producing evidence, recommending an action or actually controlling funds.

PactVerity Proof Engine v1 currently performs the evidence-processing step: it evaluates supplied latency, uptime, freshness and output-commitment data and produces a portable receipt. It does not monitor the API, decide contractual liability or move money. That separation makes the current result useful without overstating its authority.

Match the evidence to the provider’s claim process

A reproducible report can organise configured terms, sampled observations, exclusions and a provisional credit calculation. The provider’s current agreement still controls eligibility, the calculation method, the claim deadline, the submission route and the evidence it will accept.

Before relying on a report, check:

  • the covered service, account, plan, region and billing period;
  • the provider’s availability formula, thresholds, exclusions and credit cap;
  • the incident timestamps, service or API identifiers and logs it requires;
  • the claim deadline, submission channel and privacy or redaction instructions.

For example, the Amazon API Gateway SLA requires specified incident dates, times and regions, affected API IDs, the relevant billing cycle and corroborating request logs with sensitive information removed. That example shows why a PactVerity evidence package is supporting material for review—not proof of entitlement, AWS compatibility or automatic acceptance. Review the synthetic Evidence Gateway package and provisional calculation.

Verify the method and its limits

Start with the Gateway collector and evaluator instructions and published file checksums. A checksum checks file consistency; a signature also needs a trusted public key. Neither proves that a measurement source told the truth.

RFC 8032 documents Ed25519 signatures. PactVerity’s implementation and test fixtures—not that RFC alone—define how its evidence is encoded and evaluated.

Published by PactVerity, the project associated with PVTY. The free evidence tools do not require buying PVTY. This guide does not determine contractual liability.

07 / Resource hub

Continue through the verification stack.

Follow the evidence path from agent audit trails and measurable service rules to receipt anatomy, reproducible benchmarks and the working browser tools.

Collect observations and review provisional credits

Use the buyer-operated Evidence Gateway to collect authorised samples and recheck a report. No automatic settlement.

Open resource

Watch the API evidence explainer

Five minutes on latency, uptime, freshness and integrity, with the original narration transcript.

Open resource

Challenge a failure case

Inspect what the engine rejects and the boundaries of supplied evidence.

Open resource

Reproduce published fixtures

Download the dataset and inspect the method before drawing conclusions.

Open resource

Continue researching

Test the model against a working implementation.

Use the Receipt API