API v1

API Reference

Complete REST API documentation for the DingDawg Marketplace. Create agents, generate compliance reports, and manage billing programmatically.

Base URL

https://api.dingdawg.com

All API requests must use HTTPS. HTTP requests will be rejected.

Authentication

Authorization: Bearer dd_live_your_api_key

Include your API key in the Authorization header on every request. Use dd_test_* keys for sandbox.

Rate Limits

Tier	Requests / minute	Requests / day	Burst
Free	60	1,000	10
Developer	300	50,000	50
Pro	1,000	500,000	100
Enterprise	Unlimited	Unlimited	500

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Exceeding the limit returns 429 Too Many Requests.

Error Codes

Code	Meaning	Resolution
400	Bad Request	Check request body against the schema.
401	Unauthorized	Verify your API key is valid and included in the Authorization header.
403	Forbidden	Your API key does not have permission for this action.
404	Not Found	The requested resource does not exist.
409	Conflict	Agent name or version already exists. Use a unique combination.
422	Validation Error	Request body is well-formed but contains invalid values.
429	Rate Limited	Wait until X-RateLimit-Reset and retry.
500	Server Error	Retry with exponential backoff. Contact support if persistent.

Error response format

{
  "error": {
    "code": "validation_error",
    "message": "capabilities must include at least one valid capability",
    "param": "capabilities",
    "request_id": "req_abc123"
  }
}

Agents

POST/v1/agents

Create a new agent. Returns the agent object with a unique ID and sandbox status.

Request body

{
  "name": "no-show-recovery",
  "version": "1.0.0",
  "description": "Recovers missed appointments via SMS + email",
  "capabilities": ["sms.send", "email.send", "booking.read"],
  "pricing": {
    "model": "per_action",
    "price": 0.50,
    "currency": "usd"
  },
  "governance": {
    "policies_url": "https://yourcdn.com/policies.yaml"
  }
}

Response

{
  "id": "agent_abc123",
  "name": "no-show-recovery",
  "version": "1.0.0",
  "status": "sandbox",
  "capabilities": ["sms.send", "email.send", "booking.read"],
  "pricing": {
    "model": "per_action",
    "price": 0.50,
    "currency": "usd"
  },
  "created_at": "2026-03-29T12:00:00Z",
  "marketplace_url": null
}

GET/v1/agents

List all agents owned by the authenticated developer. Supports pagination and status filtering.

Response

{
  "data": [
    {
      "id": "agent_abc123",
      "name": "no-show-recovery",
      "version": "1.0.0",
      "status": "published",
      "installs": 847,
      "total_actions": 23419,
      "revenue": {
        "total": 9967.05,
        "currency": "usd"
      }
    }
  ],
  "has_more": false,
  "total": 1
}

GET/v1/agents/:agent_id

Retrieve a single agent by ID. Includes full configuration, stats, and governance status.

Response

{
  "id": "agent_abc123",
  "name": "no-show-recovery",
  "version": "1.0.0",
  "status": "published",
  "description": "Recovers missed appointments via SMS + email",
  "capabilities": ["sms.send", "email.send", "booking.read"],
  "pricing": {
    "model": "per_action",
    "price": 0.50,
    "currency": "usd"
  },
  "governance": {
    "compliant": true,
    "last_audit": "2026-03-29T08:00:00Z",
    "policies_url": "https://yourcdn.com/policies.yaml"
  },
  "stats": {
    "installs": 847,
    "total_actions": 23419,
    "avg_actions_per_day": 312,
    "success_rate": 0.994
  },
  "created_at": "2026-03-29T12:00:00Z",
  "marketplace_url": "https://dingdawg.com/marketplace/@yourname/no-show-recovery"
}

PATCH/v1/agents/:agent_id

Update an agent's description, pricing, or capabilities. Version bumps require a new publish cycle.

Request body

{
  "description": "Updated: recovers missed appointments via SMS, email, and voice",
  "capabilities": ["sms.send", "email.send", "booking.read", "voice.call"]
}

Response

{
  "id": "agent_abc123",
  "name": "no-show-recovery",
  "version": "1.0.0",
  "status": "published",
  "description": "Updated: recovers missed appointments via SMS, email, and voice",
  "capabilities": ["sms.send", "email.send", "booking.read", "voice.call"],
  "updated_at": "2026-03-29T14:30:00Z"
}

POST/v1/agents/:agent_id/publish

Submit an agent for review and publishing. The agent must pass all governance checks and smoke tests before going live.

Response

{
  "id": "agent_abc123",
  "status": "in_review",
  "review_started_at": "2026-03-29T15:00:00Z",
  "estimated_review_time": "< 24 hours"
}

POST/v1/agents/:agent_id/test

Run a smoke test against your agent in sandbox. Returns the execution result and governance receipt.

Request body

{
  "action": "recover_noshow",
  "payload": {
    "booking_id": "bk_test_001",
    "customer_phone": "+15551234567"
  }
}

Response

{
  "status": "success",
  "execution_time_ms": 340,
  "receipt": {
    "id": "rcpt_xyz789",
    "governance_status": "compliant",
    "capabilities_used": ["sms.send", "booking.read"],
    "audit_trail": "https://api.dingdawg.com/v1/receipts/rcpt_xyz789"
  },
  "result": {
    "sms_sent": true,
    "message": "Hi! We noticed you missed your 2pm appointment..."
  }
}

Compliance

POST/v1/compliance/generate

Generate a compliance report for your agent. Covers EU AI Act and SOC2 requirements. Returns a signed PDF URL.

Request body

{
  "agent_id": "agent_abc123",
  "report_type": "eu_ai_act",
  "format": "pdf"
}

Response

{
  "id": "rpt_comp_456",
  "agent_id": "agent_abc123",
  "report_type": "eu_ai_act",
  "status": "completed",
  "score": 94,
  "findings": {
    "compliant": 18,
    "warnings": 2,
    "critical": 0
  },
  "pdf_url": "https://api.dingdawg.com/v1/compliance/reports/rpt_comp_456.pdf",
  "signature": "ecdsa-sha256:abc123...",
  "generated_at": "2026-03-29T16:00:00Z",
  "valid_until": "2026-06-29T16:00:00Z"
}

GET/v1/compliance/reports

List all compliance reports for the authenticated developer. Filterable by agent_id and report_type.

Response

{
  "data": [
    {
      "id": "rpt_comp_456",
      "agent_id": "agent_abc123",
      "report_type": "eu_ai_act",
      "score": 94,
      "status": "completed",
      "generated_at": "2026-03-29T16:00:00Z"
    }
  ],
  "has_more": false,
  "total": 1
}

Billing

GET/v1/billing/summary

Get the current billing period summary. Includes total revenue, platform fees, and net payout.

Response

{
  "period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "revenue": {
    "gross": 11726.00,
    "platform_fee": 1758.90,
    "net_payout": 9967.10,
    "currency": "usd"
  },
  "actions": {
    "total": 23452,
    "billable": 23452,
    "free_tier": 0
  },
  "next_payout_date": "2026-04-15T00:00:00Z",
  "payout_method": "stripe_connect"
}

GET/v1/billing/payouts

List all past payouts. Includes amounts, dates, and Stripe transfer IDs.

Response

{
  "data": [
    {
      "id": "po_abc123",
      "amount": 8934.20,
      "currency": "usd",
      "status": "paid",
      "stripe_transfer_id": "tr_xyz789",
      "paid_at": "2026-03-15T00:00:00Z",
      "period": {
        "start": "2026-02-01T00:00:00Z",
        "end": "2026-02-28T23:59:59Z"
      }
    }
  ],
  "has_more": true,
  "total": 6
}

GET/v1/billing/usage

Get granular usage data for the current billing period. Breakdown by agent and action type.

Response

{
  "period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "agents": [
    {
      "agent_id": "agent_abc123",
      "name": "no-show-recovery",
      "actions": 23452,
      "revenue": 11726.00,
      "breakdown": {
        "sms.send": 12340,
        "email.send": 8100,
        "booking.read": 3012
      }
    }
  ]
}

Webhooks

Register a webhook URL in your developer dashboard to receive real-time event notifications. All payloads are signed with your webhook secret using HMAC-SHA256.

Webhook signature verification

import crypto from "crypto";

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Header: X-DingDawg-Signature: sha256=abc123...

Event Types

Event	Description
agent.installed	A business installed your agent.
agent.uninstalled	A business removed your agent.
agent.action.completed	Your agent completed an action successfully.
agent.action.failed	Your agent failed to complete an action.
billing.payout.created	A payout was initiated to your Stripe Connect account.
billing.payout.paid	A payout was successfully deposited.
compliance.report.ready	A compliance report finished generating.
review.approved	Your agent passed review and is now published.
review.rejected	Your agent did not pass review. Rejection reason included.

SDKs and Tools

@dingdawg/sdk

Node.js SDK for the Marketplace API. TypeScript-first.

npm install @dingdawg/sdk

@dingdawg/cli

Command-line tool for creating, testing, and publishing agents.

npm install -g @dingdawg/cli

@dingdawg/testing

Test utilities for agent smoke tests and integration testing.

npm install -D @dingdawg/testing

Ready to build?

Create a free developer account and start building your first agent. 100 free sandbox API calls per day included.

Create Developer Account Back to Developer Hub