API Reference — live at api.dingdawg.com

Developer Documentation

The complete reference for the DingDawg public API — agent discovery, governance receipts, authentication, rate limits, and error handling. Every endpoint on this page is live today.

Base URLhttps://api.dingdawg.com

Overview

Two API families, one governed runtime

The public API exposes the agent directory that powers DingDawg agent cards and A2A discovery, plus the ATR v1.0 receipt system — a verifiable record for every consequential agent decision.

Agent Discovery

Directory, cards, QR codes, A2A

List public agents, fetch profiles, render shareable card pages, generate QR codes, and read A2A v0.3 discovery documents. No authentication required.

Receipts — ATR v1.0

Verifiable decision records

Create and retrieve Agent Transaction Receipts — structured, PII-safe records of agent decisions with policy versioning and chain-of-custody links.

All endpoints return JSON unless documented otherwise (card pages return HTML, QR codes return PNG).
CORS is enabled on JSON endpoints (Access-Control-Allow-Origin: *) — call them directly from the browser.
The open receipt and protocol specs live at github.com/dingdawg (Apache 2.0).

Quickstart

Your first call in 30 seconds

No signup, no key. Pull a sample governance receipt and its schema straight from the live API.

terminal

# 1. Fetch a sample ATR v1.0 receipt — see the exact format
curl -s https://api.dingdawg.com/api/v1/public/receipt/sample

# 2. Fetch the JSON Schema it validates against
curl -s https://api.dingdawg.com/api/v1/public/receipt/schema

# 3. Browse the public agent directory
curl -s "https://api.dingdawg.com/api/v1/public/agents?limit=5"

fetch-receipt.mjs

const res = await fetch(
  "https://api.dingdawg.com/api/v1/public/receipt/sample"
);
const receipt = await res.json();

console.log(receipt.decision);        // "DECLINE"
console.log(receipt.decision_reason); // policy rule that fired
console.log(receipt.subject_id);      // SHA-256 hash — never raw PII

Authentication

Public reads, keyed writes

Agent discovery endpoints and the receipt sample/schema endpoints are fully public. Creating and retrieving stored receipts is protected by an API key.

How it works

GET endpoints under /agents, plus /receipt/sample and /receipt/schema, require no authentication.
POST /receipt and GET /receipt/{receipt_id} check the X-API-Key request header against the ATR API key configured for the deployment.
A missing or incorrect key returns 401 with {"detail": "Invalid or missing API key"}.

To request an ATR API key for your integration, contact us or email support@dingdawg.com.

terminal

# Pass your key in the X-API-Key header
export DINGDAWG_ATR_API_KEY=your-key-here

curl -s -X POST "https://api.dingdawg.com/api/v1/public/receipt" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DINGDAWG_ATR_API_KEY" \
  -d '{
    "agent_id": "@compliance-bot",
    "decision": "APPROVE",
    "subject_id": "<sha256-hash-of-subject>"
  }'

Rate limits

60 requests per minute

Public endpoints are limited to 60 requests per minute per client. Exceeding the limit returns 429 with a Retry-After header.

429 Too Many Requests — application/json

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "retry_after": 60
}

Respect the Retry-After response header before retrying. If your integration needs higher sustained throughput, contact us.

API Reference

Agent Discovery API

The public agent directory behind DingDawg agent cards, QR codes, and agent-to-agent discovery. All endpoints in this section are unauthenticated.

GET/api/v1/public/agents

List public agents

Returns the public agent directory. Supports filtering by industry and offset pagination.

Auth: None

Query parameters

Name	Type	Required	Description
industry	string	optional	Only return agents whose industry type matches this value.
limit	integer	optional	Maximum number of results to return. Default 20.
offset	integer	optional	Number of results to skip, for pagination. Default 0.

Example request

terminal

curl -s "https://api.dingdawg.com/api/v1/public/agents?limit=20&offset=0"

Example response — 200

200 OK — application/json

{
  "agents": [
    {
      "handle": "compliance-bot",
      "name": "Compliance Bot",
      "description": "Automated compliance reviews for consequential decisions",
      "industry": "fintech",
      "agent_type": "business",
      "avatar_url": "",
      "primary_color": "#7C3AED",
      "greeting": "Hi! I'm Compliance Bot. How can I help?",
      "created_at": "2026-04-02T18:11:09Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

agent_type is one of: personal, business, b2b, a2a, compliance, enterprise.
Only agents with status active appear in the directory. Sensitive configuration fields are never exposed.

GET/api/v1/public/agents/{handle}

Get an agent's public profile

Returns a single agent's full public profile, including capabilities and ready-to-use card, chat, QR, and widget embed URLs.

Auth: None

Path parameters

Name	Type	Required	Description
handle	string	required	The agent's unique @handle. The leading @ is optional — both compliance-bot and @compliance-bot resolve.

Example request

terminal

curl -s "https://api.dingdawg.com/api/v1/public/agents/compliance-bot"

Example response — 200

200 OK — application/json

{
  "handle": "compliance-bot",
  "name": "Compliance Bot",
  "description": "Automated compliance reviews for consequential decisions",
  "industry": "fintech",
  "agent_type": "business",
  "avatar_url": "",
  "primary_color": "#7C3AED",
  "greeting": "Hi! I'm Compliance Bot. How can I help?",
  "created_at": "2026-04-02T18:11:09Z",
  "capabilities": ["compliance_check", "audit_trail"],
  "card_url": "https://api.dingdawg.com/api/v1/public/agents/compliance-bot/card",
  "chat_url": "https://api.dingdawg.com/chat/compliance-bot",
  "qr_url": "https://api.dingdawg.com/api/v1/public/agents/compliance-bot/qr",
  "widget_embed_code": "<script src=\"https://api.dingdawg.com/api/v1/widget/embed.js\" data-agent=\"@compliance-bot\" data-color=\"#7C3AED\"></script>"
}

Returns 404 if the handle does not exist or the agent is not active.

GET/api/v1/public/agents/{handle}/card

Agent card page (HTML)

Returns a standalone, mobile-responsive HTML page for the agent — name, avatar, description, a chat button, and Open Graph tags for social sharing. This is the shareable link behind QR codes.

Auth: None

Path parameters

Name	Type	Required	Description
handle	string	required	The agent's unique @handle. The leading @ is optional — both compliance-bot and @compliance-bot resolve.

Example request

terminal

curl -s "https://api.dingdawg.com/api/v1/public/agents/compliance-bot/card"

Example response — 200

200 OK — text/html

<!DOCTYPE html>
<html lang="en">
  <!-- Self-contained agent card page with
       Open Graph tags and embedded chat widget -->
</html>

Responses are cached for 5 minutes (Cache-Control: public, max-age=300).

GET/api/v1/public/agents/{handle}/qr

Agent QR code (PNG)

Generates a QR code that links to the agent's card page. Businesses print this on receipts, menus, and business cards.

Auth: None

Path parameters

Name	Type	Required	Description
handle	string	required	The agent's unique @handle. The leading @ is optional — both compliance-bot and @compliance-bot resolve.

Example request

terminal

curl -s -o agent-qr.png "https://api.dingdawg.com/api/v1/public/agents/compliance-bot/qr"

Example response — 200

200 OK — image/png

Binary PNG image data.

If no QR library is available server-side, the endpoint
returns JSON instead so you can generate the code client-side:

{
  "card_url": "https://api.dingdawg.com/api/v1/public/agents/compliance-bot/card",
  "message": "QR code library not installed. Use the card_url to generate a QR code."
}

PNG responses are cached for 1 hour (Cache-Control: public, max-age=3600).

GET/api/v1/public/agents/{handle}/.well-known/agent.json

A2A discovery document

Standard agent identity document for agent-to-agent protocols, following the A2A v0.3 agent card specification. Use this to programmatically discover an agent's capabilities and endpoints.

Auth: None

Path parameters

Name	Type	Required	Description
handle	string	required	The agent's unique @handle. The leading @ is optional — both compliance-bot and @compliance-bot resolve.

Example request

terminal

curl -s "https://api.dingdawg.com/api/v1/public/agents/compliance-bot/.well-known/agent.json"

Example response — 200

200 OK — application/json

{
  "name": "Compliance Bot",
  "handle": "@compliance-bot",
  "description": "Automated compliance reviews for consequential decisions",
  "url": "https://api.dingdawg.com/api/v1/public/agents/compliance-bot/card",
  "provider": {
    "organization": "DingDawg",
    "url": "https://dingdawg.com"
  },
  "version": "1.0.0",
  "capabilities": ["compliance_check", "audit_trail"],
  "skills": [],
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "endpoints": {
    "widget_config": "https://api.dingdawg.com/api/v1/widget/compliance-bot/config",
    "widget_session": "https://api.dingdawg.com/api/v1/widget/compliance-bot/session",
    "widget_message": "https://api.dingdawg.com/api/v1/widget/compliance-bot/message",
    "public_profile": "https://api.dingdawg.com/api/v1/public/agents/compliance-bot",
    "card_page": "https://api.dingdawg.com/api/v1/public/agents/compliance-bot/card"
  },
  "protocols": {
    "a2a": "0.3",
    "dingdawg_widget": "1.0"
  },
  "authentication": {
    "schemes": ["anonymous"],
    "note": "Widget endpoints accept anonymous visitors"
  },
  "branding": {
    "primary_color": "#7C3AED",
    "avatar_url": ""
  }
}

Responses are cached for 1 hour (Cache-Control: public, max-age=3600).

API Reference

Receipts API — ATR v1.0

Agent Transaction Receipts (ATR) are structured, verifiable records of agent decisions. Sample and schema endpoints are open; creating and retrieving stored receipts requires an API key.

GET/api/v1/public/receipt/sample

Get a sample receipt

Returns a static sample ATR v1.0 receipt. Use it to inspect the exact format before integrating — no signup required.

Auth: None

Example request

terminal

curl -s "https://api.dingdawg.com/api/v1/public/receipt/sample"

Example response — 200

200 OK — application/json

{
  "receipt_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "agent_id": "@compliance-bot",
  "decision": "DECLINE",
  "decision_reason": "Transaction exceeds single-payment threshold (USD 9,500 of USD 10,000 limit)",
  "timestamp": "2026-05-28T14:30:00Z",
  "subject_id": "a3f2b8c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0",
  "policy_version": "1.4.2",
  "confidence_score": 94,
  "parent_receipt_id": null,
  "verification_endpoint": "/api/v1/public/receipt/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

GET/api/v1/public/receipt/schema

Get the ATR v1.0 JSON Schema

Returns the canonical JSON Schema for ATR v1.0 receipts. Any system can validate a receipt against this schema.

Auth: None

Example request

terminal

curl -s "https://api.dingdawg.com/api/v1/public/receipt/schema"

Example response — 200

200 OK — application/json

{
  "title": "ATR v1.0 Receipt",
  "version": "1.0.0",
  "type": "object",
  "required": ["receipt_id", "agent_id", "decision", "timestamp", "subject_id"],
  "properties": {
    "receipt_id":            { "type": "string", "format": "uuid" },
    "agent_id":              { "type": "string" },
    "decision":              { "type": "string", "enum": ["APPROVE", "DECLINE", "REVIEW"] },
    "decision_reason":       { "type": "string" },
    "timestamp":             { "type": "string", "format": "date-time" },
    "subject_id":            { "type": "string" },
    "policy_version":        { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
    "confidence_score":      { "type": "number", "minimum": 0, "maximum": 100 },
    "parent_receipt_id":     { "type": "string", "format": "uuid" },
    "verification_endpoint": { "type": "string", "format": "uri" }
  }
}

Property descriptions are included in the live response; they are trimmed here for readability.

POST/api/v1/public/receipt

Create a receipt

Stores a new ATR v1.0 receipt and returns the full record with a server-generated receipt_id and a verification endpoint.

Auth: X-API-Key header, when an ATR API key is configured for the deployment. Requests without a valid key receive 401.

Request body (JSON)

Name	Type	Required	Description
agent_id	string	required	Issuing agent identifier — a DingDawg @handle or DID.
decision	string	required	One of APPROVE, DECLINE, or REVIEW. Any other value returns 422.
subject_id	string	required	SHA-256 hash of the subject identifier. Send the hash, never the raw identifier — this keeps receipts PII-safe.
decision_reason	string	optional	Human-readable policy rule that fired.
policy_version	string	optional	Semantic version of the policy that governed this decision, e.g. 1.4.2.
confidence_score	number	optional	Agent's confidence in the decision, 0–100. Out-of-range values return 422.
parent_receipt_id	string (uuid)	optional	Chain-of-custody link to a parent receipt. Omit or null for a root receipt.

Example request

terminal

curl -s -X POST "https://api.dingdawg.com/api/v1/public/receipt" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DINGDAWG_ATR_API_KEY" \
  -d '{
    "agent_id": "@compliance-bot",
    "decision": "DECLINE",
    "decision_reason": "Transaction exceeds single-payment threshold",
    "subject_id": "a3f2b8c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0",
    "policy_version": "1.4.2",
    "confidence_score": 94
  }'

Example response — 201

201 Created — application/json

{
  "receipt_id": "7f3c1a2b-4d5e-6f70-8192-a3b4c5d6e7f8",
  "agent_id": "@compliance-bot",
  "decision": "DECLINE",
  "decision_reason": "Transaction exceeds single-payment threshold",
  "timestamp": "2026-05-28T14:30:00Z",
  "subject_id": "a3f2b8c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0",
  "policy_version": "1.4.2",
  "confidence_score": 94,
  "parent_receipt_id": null,
  "verification_endpoint": "https://api.dingdawg.com/api/v1/public/receipt/7f3c1a2b-4d5e-6f70-8192-a3b4c5d6e7f8"
}

The response includes a Location header pointing at the receipt's verification endpoint.
Validation failures (missing agent_id or subject_id, invalid decision, out-of-range confidence_score) return 422 with a detail message.

GET/api/v1/public/receipt/{receipt_id}

Retrieve a receipt

Fetches a stored receipt by its UUID. This is the verification endpoint printed on every receipt — anyone holding a receipt ID and a valid key can independently verify the record.

Auth: X-API-Key header, when an ATR API key is configured for the deployment. Requests without a valid key receive 401.

Path parameters

Name	Type	Required	Description
receipt_id	string (uuid)	required	The UUID of the receipt to retrieve.

Example request

terminal

curl -s "https://api.dingdawg.com/api/v1/public/receipt/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: $DINGDAWG_ATR_API_KEY"

Example response — 200

200 OK — application/json

{
  "receipt_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "agent_id": "@compliance-bot",
  "decision": "DECLINE",
  "decision_reason": "Transaction exceeds single-payment threshold (USD 9,500 of USD 10,000 limit)",
  "timestamp": "2026-05-28T14:30:00Z",
  "subject_id": "a3f2b8c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0",
  "policy_version": "1.4.2",
  "confidence_score": 94,
  "parent_receipt_id": null,
  "verification_endpoint": "/api/v1/public/receipt/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Unknown receipt IDs return 404.

Receipts & governance

The ATR v1.0 receipt object

Every receipt answers four questions: who decided (agent_id), what was decided (decision + reason), when (timestamp), and under which rules (policy_version). The subject is stored only as a SHA-256 hash, so receipts stay PII-safe by construction.

Fields

Name	Type	Required	Description
receipt_id	string (uuid)	required	Unique receipt identifier (UUIDv4), generated by the server.
agent_id	string	required	Issuing agent identifier — a DingDawg @handle or DID.
decision	enum	required	The agent's decision: APPROVE, DECLINE, or REVIEW.
decision_reason	string	optional	Human-readable policy rule that fired.
timestamp	string (date-time)	required	ISO 8601 UTC timestamp of the decision.
subject_id	string	required	SHA-256 hash of the subject identifier — PII never enters the receipt.
policy_version	string (semver)	optional	Semantic version of the policy that governed this decision.
confidence_score	number (0–100)	optional	Agent's confidence in the decision.
parent_receipt_id	string (uuid)	optional	Chain-of-custody link to a parent receipt; null for a root receipt.
verification_endpoint	string (uri)	optional	Self-referential URL for independently verifying this receipt.

How receipt fields map to record-keeping duties

ATR receipts are designed as the technical substrate for the record-keeping obligations that AI regulations impose on consequential decisions. The mapping below is engineering documentation — it is not legal advice and does not by itself make a system compliant.

Regulation	Record-keeping duty	Relevant receipt fields
EU AI Act — Art. 12 (Record-keeping)	High-risk AI systems must automatically record events over the system lifetime.	receipt_id, agent_id, decision, timestamp, policy_version
Colorado SB 24-205 (Consumer AI Act)	Developers and deployers of high-risk systems must document consequential decisions and support review and appeal.	decision, decision_reason, subject_id (hashed), the REVIEW decision path
Texas TRAIGA	Responsible AI governance duties for covered systems, including records that evidence how a decision was made.	decision_reason, policy_version, confidence_score, parent_receipt_id chain

Available today vs. spec

The ATR v1.0 endpoints documented above are live today on api.dingdawg.com. The broader open protocol work — including the DGP specification — is published at github.com/dingdawg under Apache 2.0 and is the canonical source for spec-level capabilities that are not yet exposed as hosted endpoints.

Error handling

Status codes and error shape

Errors return a JSON body with a detail field describing what went wrong. Rate-limit errors use a dedicated shape with retry_after.

Status	Meaning	Example
200 / 201	Success. 201 is returned when a receipt is created.	—
401	Missing or invalid X-API-Key on a protected receipt endpoint.	{"detail": "Invalid or missing API key"}
404	Agent handle or receipt ID not found (inactive agents also return 404).	{"detail": "Agent not found"}
422	Request body failed validation.	{"detail": "decision must be APPROVE, DECLINE, or REVIEW"}
429	Rate limit exceeded — retry after the Retry-After interval.	{"error": "rate_limit_exceeded", ...}
503	A required backing service is unavailable. Retry with backoff.	{"detail": "Agent registry not initialised"}

SDKs & tools

Published packages

Open-source tooling published on npm and PyPI. Both packages run locally with no signup.

dingdawg-governance

npm

MCP governance server for Claude Code, Cursor, and any MCP-compatible agent. Adds a pre-execution gate that issues a receipt for every governed action. Apache 2.0, works fully offline — an API key unlocks cloud sync.

terminal

npm install dingdawg-governance

# or add straight to Claude Code:
claude mcp add dingdawg-governance npx dingdawg-governance

MCP tools: govern_action, audit_trail, compliance_check, rollback_action, register_agent, ipfs_proof. Source: github.com/dingdawg/governance-sdk

dingdawg-compliance

PyPI

Colorado SB 205 compliance scanner. Scores your readiness across all 25 SB 205 controls — impact assessments, transparency, appeal mechanisms, bias testing, and audit trails. Free, stdlib-only, runs entirely locally.

terminal

pip install dingdawg-compliance
python3 -m dingdawg_compliance scan

Requires Python 3.9+. No external dependencies.

Integrating a framework? Integration guides cover CrewAI, LangGraph, Claude Code, and Cursor with copy-paste configuration for each.

Build against the contract

Everything on this page is verifiable against the live API. Found a gap in the docs, or need an ATR API key for your integration? Tell us — developer feedback shapes what we document next.

Request an API Key Send Docs Feedback See Plans