From zero to a verified receipt in a minute.
One endpoint creates receipts, one verifies them. Clients are single files with no dependencies.
Quickstart
- Sign up and confirm your email. Your first key is created for you and shown once.
- Paste the block below. It signs one request and prints a link to verify the receipt in your browser.
curl -fsSO https://attestras.vercel.app/sdk/attestras.py
export ATTESTRAS_URL=https://attestras.vercel.app
export ATTESTRAS_SOURCE=my-first-source
export ATTESTRAS_KEY_ID=ak_xxxxxxxxxxxx
export ATTESTRAS_SECRET=atsec_xxxxxxxxxxxxxxxx # shown once when you create the key
python3 attestras.py demoPython
from attestras import Attestras
import hashlib, os
a = Attestras(os.environ["ATTESTRAS_URL"], source=os.environ["ATTESTRAS_SOURCE"],
key_id=os.environ["ATTESTRAS_KEY_ID"], secret=os.environ["ATTESTRAS_SECRET"])
report = open("report.json", "rb").read()
receipt = a.attest(
artifact_uri="https://storage.example.com/runs/42/report.json", # host must be on your allowlist
artifact_sha256=hashlib.sha256(report).hexdigest(),
actor="agent-run-42",
assertion="agent produced report.json",
request_id="run-42-report", # idempotency key: retries return the same receipt
)
print(receipt["proof_id"], receipt["proof_hash"])
print(a.verify(receipt["proof_id"], receipt["proof_hash"]))Node
import { Attestras } from "./attestras.mjs";
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
const a = new Attestras({ baseUrl: process.env.ATTESTRAS_URL, source: process.env.ATTESTRAS_SOURCE,
keyId: process.env.ATTESTRAS_KEY_ID, secret: process.env.ATTESTRAS_SECRET });
const receipt = await a.attest({
artifactUri: "https://storage.example.com/runs/42/report.json",
artifactSha256: createHash("sha256").update(readFileSync("report.json")).digest("hex"),
actor: "agent-run-42", assertion: "agent produced report.json", requestId: "run-42-report",
});
console.log(receipt, await a.verify(receipt.proof_id, receipt.proof_hash));Protocol
POST /v1/proofs with Content-Type: application/json and these headers:
| Header | Value |
|---|---|
X-Source-System | Your source name, as set when you created the key. |
X-Key-ID | The key ID, ak_…. |
X-Request-ID | Your idempotency key for this event. Letters, digits, . _ : -, up to 128 characters. |
X-Timestamp | Unix seconds. Must be within 30 seconds of our clock. |
X-Signature-Version | pg-hmac-sha256-v1 |
X-Signature | Lower-case hex HMAC-SHA256, keyed with your secret, over the preimage below. |
Preimage: the bytes PGSIG\x01 followed by these six fields, each prefixed with its length as a 4-byte big-endian integer: signature version, timestamp, request ID, source, key ID, then the exact request body. The clients above do this for you; a reference implementation is 6 lines.
Body: artifact.uri (HTTPS, host on your allowlist, no query string), artifact.file_hash (SHA-256, 64 hex), actor.external_ref (an opaque ID for the agent or run, up to 256 characters; pseudonymised before storage) and claim with schema: "pg.claim.v1" and a short assertion. Unknown fields are rejected. Do not send personal data. These patterns are refused: email addresses, phone numbers, UK National Insurance numbers and any bare 9-digit number (so avoid 9-digit run IDs in assertion text).
Response: 201 with proof_id and proof_hash on first send, 200 with the same values on a safe replay. Keep both; the pair is the receipt.
Check one of your own receipts
With your key you can fetch the stored record behind any receipt you made and recompute its hash on your machine: python3 attestras.py check PROOF_ID (Node: node attestras.mjs check PROOF_ID). It is POST /v1/records, signed like a create request, free, and only your own tenant can read it. Details on the protocol page.
Verify
curl -s https://attestras.vercel.app/v1/verify \
-H 'Content-Type: application/json' \
-d '{"proof_id":"pg_…","proof_hash":"…64 hex…"}'
# 200 {"verified":true,"proof_id":…,"proof_hash":…,"source_system_id":…,"artifact_hash":…,"claim_schema":…,"recorded_at":…}
# 404 {"verified":false}Verification is unlimited and free. It reveals the proof ID, hash, source name, artifact SHA-256, claim schema and recorded time, nothing else. Please do not enumerate IDs; see the acceptable use policy.
Errors
| Status | Meaning |
|---|---|
400 | Malformed JSON, missing field, unsupported claim schema, artifact host not on your allowlist, or a privacy pattern found in the payload (email address, phone number, 9-digit number such as a US SSN, UK National Insurance number). |
401 | Missing or invalid signature, unknown or revoked key, stale timestamp. Always the same opaque answer. |
402 | Monthly receipt allowance used. The body carries limit, plan and upgrade_url. Safe retries of earlier requests still work. |
409 | Same request ID, different content. Send a new request ID for a new event. |
413 / 415 | Body over 50 KB, or Content-Type is not application/json. |
503 | Storage unavailable. Retry with the same request ID; it is safe. |
Limits
- Body up to 50 KB, JSON nesting up to 32 levels, no floating-point numbers (use strings or integers so the record is deterministic).
- Allowances reset on the 1st of the month, 00:00 UTC. Safe retries and verification do not count.
- Artifact hosts: set the HTTPS hosts you store artifacts on in your account. New accounts start with
example.comso the quickstart works.
Machine-readable spec
OpenAPI 3 document. Clients: attestras.py, attestras.mjs.