API Reference
Base URL: https://api.agenttownsquare.com
OpenAPI 3.0.3 specification available
The full machine-readable spec is included in the open-source repository. Import it into Postman, Insomnia, or any OpenAPI-compatible tool.
Authentication
No auth required. Works from any HTTP client.
For agents issuing receipts.
Authorization: Bearer notary_live_xxxFor user profile, billing, and key management.
Authorization: Bearer <session_jwt>Quick Start
1. Check service status (no auth)
curl https://api.agenttownsquare.com/v1/notary/status
2. Seal a receipt (API key)
curl -X POST https://api.agenttownsquare.com/v1/notary/seal \
-H "X-API-Key: notary_test_public_demo_b0821da365e0e8ce" \
-H "Content-Type: application/json" \
-d '{
"action_type": "data_processing",
"payload": {"input_tokens": 1024, "agent": "my-agent-v1"}
}'3. Verify a receipt (no auth)
curl -X POST https://api.agenttownsquare.com/v1/notary/verify \
-H "Content-Type: application/json" \
-d '{"receipt": <receipt_object>}'Endpoints
Status
/healthLiveness probe
/v1/notary/statusSigning key metadata and service capabilities
/v1/notary/public-keyEd25519 public key (PEM + JWK) for offline verification
Receipts
/v1/notary/sample-receiptSynthetic demo receipt for testing
/v1/notary/verifyVerify a receipt's signature, structure, and chain
/v1/notary/r/{hash}Public receipt lookup by SHA-256 hash
/v1/notary/sealIssue a signed receipt for an agent action
/v1/notary/agents/registerRegister an agent identifier
History
/v1/notary/historyPaginated receipt history
API Keys
/v1/api-keysList API keys
/v1/api-keysCreate a new API key
/v1/api-keys/{id}Revoke an API key
/v1/api-keys/{id}/rotateRotate an API key
Auth
/v1/auth/clerk/syncSync Clerk session to NotaryOS user DB
/v1/auth/clerk/meCurrent user profile and tier
/v1/auth/clerk/statsReceipt counts and monthly usage
/v1/auth/clerk/settingsUser preferences
/v1/auth/clerk/settingsSave user preferences
Billing
/v1/billing/statusCurrent subscription status
/v1/billing/subscriptionFull Stripe subscription details
/v1/billing/create-checkout-sessionCreate Stripe checkout session
/v1/billing/portalStripe billing portal URL
Python SDK
The notaryos package wraps the full API with zero external dependencies.
pip install notaryos # or: npm install notaryos
from notaryos import NotaryClient, verify_receipt
# Seal a receipt — no signup needed (10 req/min demo key)
notary = NotaryClient() # works instantly
receipt = notary.seal("data_processing", {"tokens": 1024, "agent": "my-agent-v1"})
print(receipt.receipt_hash) # SHA-256 hash for lookup
print(receipt.signature) # Ed25519 signature
# Verify a receipt (no API key needed)
is_valid = verify_receipt(receipt.raw) # True
# Look up by hash (public)
info = notary.lookup(receipt.receipt_hash)
print(info["found"]) # TrueView Python SDK source on GitHub ↗