gRPC first, REST where you need it.
One protobuf schema. Four services: Govern, Attest, Log, Verify. A REST gateway for tools that don't speak gRPC. Stable v1 contracts, versioned evolution, no silent breaking changes.
Our APIs live in a single set of protobuf files published under a stable v1 namespace. The gRPC endpoint is the canonical surface; a REST/JSON gateway mirrors it for curl, webhooks, and tooling that prefers HTTP.
Transport and authentication
Both surfaces enforce mTLS with tenant-scoped client certificates plus OIDC workload identity where available. Every mutating call is idempotent on a client-supplied request_id. Re-sending the same signed decision returns the original log inclusion proof rather than creating a duplicate record, which matters for retry loops across flaky networks.
Core services
Attest — Sign
POST /v1/attest:sign or Attest.Sign RPC. Input: the AI system id, canonical request, canonical response, model version, confidence, and any policy-enforcement records. Output: an Ed25519 signature (produced by your KMS), the canonical payload hash, and a synchronous transparency-log inclusion proof. Typical p50 end-to-end under 40ms.
Log — Append and query
Log.Append is called transparently by Attest.Sign, and also exposed directly for non-AI evidence (policy approvals, incident reports, access events). Log.GetInclusionProof, Log.GetConsistencyProof, and Log.GetSignedTreeHead expose the Merkle primitives needed to audit the tree without trusting Veridra, using the same calls our witness partners run.
Verify — Offline and online
Verify.CheckSignature and Verify.CheckInclusion validate a record against a public key and a signed tree head. Neither call requires a round-trip to tenant data; they're stateless and can run from anywhere that can resolve your public key. The same logic is embedded in every SDK and in the veridra-verify CLI.
EvidencePack — Bundle
EvidencePack.Create packages signed decisions, policy records, incidents, and inclusion proofs over a date range or case id into a single signed PDF plus ZIP. Output is itself logged, so the act of producing evidence is itself attested. EvidencePack.Verify re-validates a received pack end to end.
Versioning and stability
Schema evolution
v1 is stable. Additive fields only; removals and semantic changes move to v2 under a parallel namespace. Deprecations carry 12-month notice with both versions served simultaneously.
Error model
Canonical gRPC status codes plus a typed ErrorDetailspayload with a stable reason enum that's safe to branch on in client code. REST returns RFC 7807 problem documents with the same reason codes.
Rate limits and backpressure
Per-tenant quotas surfaced as x-veridra-rate-* headers and gRPC metadata. Signer saturation returns RESOURCE_EXHAUSTED with a retry-after hint, and SDKs honor it automatically.