# Kudosity — Full Documentation for AI Agents

> Complete reference for autonomous AI agents integrating with the Kudosity communications platform.

---

## Table of Contents

1. Overview
2. Getting Started (Self-Registration)
3. Authentication
4. Sending Messages
5. Safety Engine
6. Agent Profiles
7. Conversations
8. Usage & Analytics
9. MCP Server Tools
10. API Reference
11. Sandbox vs Production
12. Safety Policies
13. Webhooks
14. Error Handling
15. Rate Limits

---

## 1. Overview

Kudosity is a managed communications platform for AI agents. It provides:

- **Multi-channel messaging**: SMS, email, voice, WhatsApp, Telegram
- **Built-in safety**: 6-layer safety engine that cannot be bypassed
- **Regulatory compliance**: TCPA quiet hours, opt-out management, content filtering
- **Self-service onboarding**: Register autonomously via MCP or API
- **Tiered access**: Sandbox for testing, production for real messaging

Every message passes through the safety engine before delivery. This protects recipients, ensures compliance, and prevents abuse.

---

## 2. Getting Started (Self-Registration)

Kudosity supports fully autonomous agent onboarding. No human dashboard login required.

### Prerequisites

- None. Just provide your agent name to get started.

### Step-by-Step

**Step 1: Register**

```
POST /api/v1/register
Content-Type: application/json

{
  "agent_name": "My Support Agent",
  "description": "Handles customer appointment reminders",
  "system_prompt": "You are a helpful appointment reminder agent."
}
```

Only `agent_name` is required. `description` and `system_prompt` are optional.

Response:
```json
{
  "api_key": "kd_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "account_id": "uuid",
  "agent_profile_id": "uuid",
  "environment": "sandbox",
  "limits": {
    "rate_limit": "10 requests/minute",
    "recipients": "Test numbers only (+61400000xxx)"
  },
  "next_step": "Use this API key as a Bearer token to call /api/v1/messages and send test messages."
}
```

Save the `api_key` — it is shown only once. A sandbox key is returned immediately. No email, phone, or human verification is needed for sandbox access.

**Step 2: Send Test Messages**

Use the sandbox key to send messages to test numbers only (`+61400000xxx`):

```
POST /api/v1/messages
Authorization: Bearer kd_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "to": "+61400000001",
  "content": "Hello from my agent!"
}
```

**Step 3: Upgrade to Production**

When ready for production, the account owner provides their email, mobile, and business details via the `/verify` page. Once verified, a production key (`kd_live_`) is issued that can send to real recipients.

---

## 3. Authentication

### API Key Authentication

All authenticated endpoints use Bearer token authentication:

```
Authorization: Bearer kd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Key formats:
- `kd_test_` — Sandbox keys (test numbers only)
- `kd_live_` — Production keys (real recipients)

### Scopes

API keys have scopes that control access:
- `messages:send` — Send messages, check message status
- `messages:read` — Read conversations and message history
- `agents:read` — List and view agent profiles
- `agents:write` — Create and update agent profiles

### Rate Limiting

Per-key rate limits are enforced. Default: 60 requests/minute (sandbox: 10/minute).

When rate-limited, the response includes:
```
HTTP 429 Too Many Requests
Retry-After: <seconds>
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
```

---

## 4. Sending Messages

### Send a Message

```
POST /api/v1/messages
Authorization: Bearer kd_live_...

{
  "to": "+61412345678",
  "content": "Your appointment is tomorrow at 2pm.",
  "channel": "sms",
  "agent_id": "uuid-or-slug",
  "sender_id": "uuid",
  "metadata": { "appointment_id": "abc123" }
}
```

Required fields: `to`, `content`
Optional: `channel` (default: "sms"), `agent_id`, `sender_id`, `metadata`

### Idempotency

Include an `Idempotency-Key` header to prevent duplicate sends:

```
Idempotency-Key: unique-request-id-123
```

If the same key is sent within 24 hours, the original response is replayed with header `Idempotency-Replayed: true`.

### Response States

**Sent (201)**:
```json
{
  "id": "uuid",
  "status": "sent",
  "provider_message_id": "provider-id",
  "safety": { "checks_passed": true }
}
```

**Blocked by Safety (403)**:
```json
{
  "id": "uuid",
  "status": "blocked",
  "safety": {
    "checks_passed": false,
    "denied_reason": "Rate limit exceeded: max 5 per hour to this recipient",
    "checks": { ... }
  }
}
```

**Provider Failure (502)**:
```json
{
  "id": "uuid",
  "status": "failed",
  "error": "Provider timeout",
  "safety": { "checks_passed": true }
}
```

### Check Message Status

```
GET /api/v1/messages/{id}
Authorization: Bearer kd_live_...
```

Returns current delivery status, provider message ID, safety result, and timestamps.

---

## 5. Safety Engine

Every message passes through 6 safety checks. These cannot be disabled or bypassed.

### Checks (run in parallel)

| # | Check | What It Does | Default |
|---|-------|-------------|---------|
| 1 | Opt-In | Verifies recipient has opted in to receive messages | Required |
| 2 | Blocklist | Checks global and per-agent blocklists | Block if listed |
| 3 | Rate Limit | Limits messages per recipient per hour | 5/hour |
| 4 | Quiet Hours | Blocks messages during rest hours | 21:00–08:00 AEDT |
| 5 | Content Filter | Enforces max message length and content rules | 1600 chars |
| 6 | NLP Filter | AI-powered content evaluation (optional, per-agent) | Disabled |

### How It Works

- All checks run on every message, every time
- If ANY check fails, the message is blocked (not sent)
- Blocked messages are still logged with full safety details
- Safety events are recorded for audit and analytics
- Webhook events fire for blocked messages (`safety.blocked`)

### Per-Agent Overrides

Agent profiles can customize thresholds (but cannot disable checks):

```json
{
  "safety_config": {
    "rate_limit": { "max_per_hour": 10 },
    "quiet_hours": { "start": "22:00", "end": "07:00", "timezone": "Australia/Sydney" },
    "content_filter": { "max_length": 480 },
    "nlp_filter": { "enabled": true, "threshold": 70 }
  }
}
```

---

## 6. Agent Profiles

Agent profiles represent distinct AI identities on the platform. Each agent can have its own safety config, system prompt, and metadata.

### List Agents

```
GET /api/v1/agents
Authorization: Bearer kd_live_...
```

### Get Agent

```
GET /api/v1/agents/{id}
Authorization: Bearer kd_live_...
```

The `id` can be a UUID or a slug (e.g., "support-bot").

### Create Agent

```
POST /api/v1/agents
Authorization: Bearer kd_live_...

{
  "name": "Appointment Reminder",
  "slug": "appointment-reminder",
  "description": "Sends appointment reminders 24h before scheduled time",
  "type": "outbound",
  "system_prompt": "You are a polite appointment reminder agent.",
  "safety_config": { ... },
  "metadata": { "department": "scheduling" }
}
```

Types: `outbound` (sends only), `inbound` (receives only), `bidirectional` (both)

### Update Agent

```
PATCH /api/v1/agents/{id}
Authorization: Bearer kd_live_...

{
  "description": "Updated description",
  "is_active": false
}
```

Only provided fields are updated.

### Delete Agent

```
DELETE /api/v1/agents/{id}
Authorization: Bearer kd_live_...
```

---

## 7. Conversations

Messages are automatically grouped into conversation threads by recipient and agent.

### List Conversations

```
GET /api/v1/conversations?agent_id=uuid&status=active&limit=50&offset=0
Authorization: Bearer kd_live_...
```

### Get Conversation

```
GET /api/v1/conversations/{id}
Authorization: Bearer kd_live_...
```

### Get Conversation Messages

```
GET /api/v1/conversations/{id}/messages?limit=50&offset=0
Authorization: Bearer kd_live_...
```

---

## 8. Usage & Analytics

### Get Usage Statistics

```
GET /api/v1/usage?period=7d&agent_id=uuid
Authorization: Bearer kd_live_...
```

Periods: `24h`, `7d`, `30d`

Response:
```json
{
  "data": {
    "period": "7d",
    "since": "2026-03-06T00:00:00Z",
    "total": 142,
    "outbound": {
      "total": 130,
      "sent": 120,
      "delivered": 115,
      "failed": 5,
      "blocked": 5,
      "delivery_rate": 92,
      "block_rate": 4
    },
    "inbound": 12
  }
}
```

---

## 9. MCP Server Tools

The Kudosity MCP server exposes 8 tools via stdio transport (JSON-RPC).

### Connection

```json
{
  "mcpServers": {
    "kudosity": {
      "command": "node",
      "args": ["path/to/mcp/build/server.js"],
      "env": {
        "KUDOSITY_API_KEY": "kd_live_...",
        "KUDOSITY_BASE_URL": "https://kudosity.vercel.app"
      }
    }
  }
}
```

The API key is optional — without it, only `register_agent` is available.

### Tools

| Tool | Description | Auth Required |
|------|-------------|---------------|
| `register_agent` | Self-register and get sandbox API key | No |
| `send_message` | Send SMS through safety engine | Yes (messages:send) |
| `list_agents` | List all agent profiles | Yes (agents:read) |
| `get_agent` | Get agent by ID or slug | Yes (agents:read) |
| `create_agent` | Create new agent profile | Yes (agents:write) |
| `update_agent` | Update agent profile | Yes (agents:write) |
| `get_usage` | Query usage statistics | Yes (any scope) |
| `get_message_status` | Check message delivery status | Yes (messages:send) |

### register_agent

Self-registration for autonomous agents. Just provide your name to get a sandbox key.

Parameters:
- `agent_name` (required): Your display name
- `description` (optional): What your agent does
- `system_prompt` (optional): Your persona/instructions

Returns a sandbox API key immediately. No email, phone, or human verification needed.

### send_message

Send an SMS message through the safety engine.

Parameters:
- `to` (required): Recipient phone in E.164 format
- `content` (required): Message text (max 1600 chars)
- `agent_id` (optional): Agent profile UUID or slug
- `sender_id` (optional): Sender ID / from number
- `metadata` (optional): Key-value pairs to attach

### list_agents

No parameters. Returns all agent profiles for the account.

### get_agent

Parameters:
- `id` (required): Agent UUID or slug

### create_agent

Parameters:
- `name` (required): Display name
- `slug` (optional): URL-safe identifier
- `description` (optional): Agent description
- `type` (optional): "outbound", "inbound", or "bidirectional"
- `system_prompt` (optional): System instructions
- `safety_config` (optional): Per-agent safety overrides
- `metadata` (optional): Arbitrary metadata

### update_agent

Parameters:
- `id` (required): Agent UUID or slug
- All create_agent fields (optional)
- `is_active` (optional): Enable/disable agent

### get_usage

Parameters:
- `period` (optional): "24h", "7d", or "30d"
- `agent_id` (optional): Filter by agent

### get_message_status

Parameters:
- `id` (required): Message UUID

---

## 10. API Reference

Base URL: `https://kudosity.vercel.app/api/v1`

### Public Endpoints (No Auth)

| Method | Path | Description |
|--------|------|-------------|
| GET | /health | Platform health check |
| POST | /register | Agent self-registration |
| POST | /register/upgrade | Production upgrade |

### Authenticated Endpoints (Bearer Token)

| Method | Path | Scope | Description |
|--------|------|-------|-------------|
| POST | /messages | messages:send | Send a message |
| GET | /messages/{id} | messages:send | Get message status |
| GET | /agents | agents:read | List agent profiles |
| POST | /agents | agents:write | Create agent profile |
| GET | /agents/{id} | agents:read | Get agent profile |
| PATCH | /agents/{id} | agents:write | Update agent profile |
| DELETE | /agents/{id} | agents:write | Delete agent profile |
| GET | /conversations | messages:read | List conversations |
| GET | /conversations/{id} | messages:read | Get conversation |
| GET | /conversations/{id}/messages | messages:read | Get conversation messages |
| GET | /usage | any | Usage statistics |

---

## 11. Sandbox vs Production

| Feature | Sandbox (kd_test_) | Production (kd_live_) |
|---------|-------------------|----------------------|
| Recipients | Test numbers only (+61400000xxx) | Any valid number |
| Rate limit | 10 req/min | 60 req/min |
| Safety engine | Full | Full |
| Message logging | Yes | Yes |
| Analytics | Yes | Yes |
| Webhooks | Yes | Yes |
| Cost | Free | Usage-based |

### Upgrading

When ready for production, the account owner provides their details via the `/verify` page:
- Email and mobile number (for identity verification)
- Business name
- Activity description (what the agent will communicate about)
- Expected monthly message volume
- Website (optional)

Upon verification, a production API key (`kd_live_`) is issued.

---

## 12. Safety Policies

Kudosity includes 13 pre-built safety policy templates.

### Core Policies

| Policy | Rate Limit | Quiet Hours | Max Length | PII Handling |
|--------|-----------|-------------|-----------|-------------|
| Default | 5/hr | 21:00–08:00 | 1600 | Warn |
| Strict | 3/hr | 20:00–09:00 | 480 | Block |
| Financial Services | 5/hr | 20:00–08:00 | 1600 | Block |
| Healthcare | 3/hr | 20:00–08:00 | 1600 | Redact |
| Marketing/Campaigns | 10/hr | 21:00–08:00 | 1600 | Warn |
| Transactional | 20/hr | None | 1600 | Redact |

### Industry Compliance Packs

| Pack | Regulation | Rate Limit | Quiet Hours | Max Length | PII |
|------|-----------|-----------|-------------|-----------|-----|
| Debt Collections | FDCPA | 2/hr | 21:00–08:00 ET | 480 | Block |
| Insurance | General | 5/hr | 21:00–08:00 ET | 1600 | Redact |
| Real Estate | General | 5/hr | 20:00–09:00 | 1600 | Warn |
| Education | FERPA | 5/hr | 21:00–08:00 ET | 1600 | Redact |
| Government | General | 3/hr | 20:00–08:00 | 1600 | Block |
| Hospitality | General | 10/hr | 22:00–07:00 | 1600 | Warn |
| AU Telemarketing | ACMA | 3/hr | 20:00–09:00 | 480 | Block |

Apply a policy by setting `safety_config` on your agent profile.

---

## 13. Webhooks

Kudosity delivers webhook events for message lifecycle and safety events.

### Event Types

| Event | Description |
|-------|-------------|
| `message.sent` | Message delivered to provider |
| `message.failed` | Message delivery failed |
| `safety.blocked` | Message blocked by safety engine |

### Payload Format

```json
{
  "event": "message.sent",
  "timestamp": "2026-03-13T12:00:00Z",
  "data": {
    "log_id": "uuid",
    "conversation_id": "uuid",
    "recipient": "+61412345678",
    "channel": "sms",
    "agent_profile_id": "uuid",
    "provider_message_id": "provider-id",
    "status": "sent"
  }
}
```

### Retry Policy

Failed webhook deliveries are retried automatically with exponential backoff.

---

## 14. Error Handling

### Standard Error Response

```json
{
  "error": "Description of what went wrong"
}
```

### HTTP Status Codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created (new message, new agent) |
| 400 | Invalid request (missing/invalid fields) |
| 401 | Unauthorized (missing or invalid API key) |
| 403 | Forbidden (insufficient scope, sandbox restriction, safety block) |
| 404 | Not found |
| 429 | Rate limited |
| 500 | Internal server error |
| 502 | Provider error (message passed safety but delivery failed) |

### Safety Block Response

When a message is blocked, the response includes detailed check results so your agent can understand why and adjust:

```json
{
  "id": "uuid",
  "status": "blocked",
  "safety": {
    "checks_passed": false,
    "denied_reason": "Quiet hours: messages blocked between 21:00 and 08:00 AEDT",
    "checks": {
      "optIn": { "passed": true },
      "blocklist": { "passed": true },
      "rateLimit": { "passed": true },
      "quietHours": { "passed": false, "reason": "..." },
      "contentFilter": { "passed": true }
    }
  }
}
```

---

## 15. Rate Limits

### API Rate Limits (per key)

| Key Type | Limit |
|----------|-------|
| Sandbox (kd_test_) | 10 requests/minute |
| Production (kd_live_) | 60 requests/minute |

### Message Rate Limits (per recipient, per agent)

| Policy | Default |
|--------|---------|
| Standard | 5 messages/hour per recipient |
| Marketing | 10 messages/hour per recipient |
| Transactional | 20 messages/hour per recipient |
| Strict | 3 messages/hour per recipient |

These are enforced by the safety engine and can be configured via agent `safety_config`.

---

## OpenAPI Specification

A machine-readable OpenAPI 3.1 specification is available at:

```
/docs/openapi.yaml
```

This can be used to auto-generate client libraries in any language.