Welcome to Dwrrah

The Basics

Resources

The Dwrrah Public API lets your academy automate its own data — courses, students, enrollments, live sessions, certificates, analytics, and outbound webhooks. It's a Pro-plan feature.

Base URL: https://api.dwrrah.com/v1

1. Create an API key

In your academy dashboard, go to Settings → Developers → API Keys and create a key. The key is shown once at creation — store it securely. Each key belongs to exactly one academy, and its scopes are derived from the key.

2. Make your first request (read)

curl https://api.dwrrah.com/v1/academy -H "Authorization: Bearer dwr_live_…"

3. Make a write request

Writes affect your academy directly. Send an Idempotency-Key to make retries safe:

curl -X POST https://api.dwrrah.com/v1/webhooks/endpoints -H "Authorization: Bearer dwr_live_…" -H "Content-Type: application/json" -H "Idempotency-Key: 3f1c2b7a-…" -d '{"url":"https://example.com/hook","events":["session.booked"]}'

Using n8n / Make

Use an HTTP Request node: set the URL to the endpoint, add a header Authorization: Bearer dwr_live_…, and an Idempotency-Key for writes. On 429, wait the Retry-After seconds, then retry.

Every request must send your academy API key as a Bearer token: Authorization: Bearer dwr_live_xxxxxxxxxxxx

How keys work

• Keys are created in Settings → Developers → API Keys in your dashboard.
• The key is shown once at creation — store it securely.
• Each key belongs to exactly one academy. The academy_id and granted scopes are derived server-side from the key — you can never pass an academy_id to act on another academy.
• Keys are managed only from the dashboard (create, rotate, revoke). There is no key-management endpoint, so a key can never mint or revoke another key.

Missing or invalid key

Returns HTTP 401 with { "error": { "code": "unauthorized" } }.

Test keys

Test keys help you label and organize integrations, but they do not run in an isolated sandbox — every key acts on your own academy data, and writes affect your account directly. Responses to a test key include the header X-Dwrrah-Environment-Warning: test_keys_act_on_live_account, so you can spot test traffic in your logs.

Every endpoint requires a specific scope. A key only carries the scopes you granted it — always grant the least privilege an integration needs. A request missing a required scope returns HTTP 403 with missing_scope.

How scopes work

• Each operation declares its required scope (shown as Required scopes on every reference page).
• Read and write are separate — e.g. courses.read never allows writes.
• Start with read-only keys, and add write scopes only when needed.

Available scopes

Idempotency

Send an Idempotency-Key header on write requests (POST / PATCH) to make them safely retryable — a network blip won't create a duplicate.

curl -X POST https://api.dwrrah.com/v1/enrollments -H "Authorization: Bearer dwr_live_…" -H "Idempotency-Key: 3f1c2b7a-…" -d '{"student_id":"stu_77aa","course_id":"crs_9a8b"}'

• Repeating the same key returns the original result — no duplicate.
• Reusing a key with a different body returns 409 idempotency_conflict.
• Use a fresh unique key (e.g. a UUID) per logical operation.

Reversible writes & rollback

Every write response includes an operation object. When reversible is true, undo the write:

curl -X POST https://api.dwrrah.com/v1/operations/{operation_id}/rollback -H "Authorization: Bearer dwr_live_…"

Rollback is idempotent and scoped to your academy.

The API applies per-minute rate limits per key and request category.

Limits

Writes and generation are intentionally stricter.

Rate-limit headers

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

When you hit the limit

The API returns 429 with a Retry-After header. Wait that many seconds before retrying, and use exponential backoff for long-running automations.

Error shape

All errors return { "error": { "code": "...", "message": "..." }, "request_id": "req_…" }.

Webhooks deliver signed, real-time events to an HTTPS endpoint you register — enrollments, bookings, certificates, payments, and more. They're the push companion to the queryable Event Stream.

1. Register an endpoint

curl -X POST https://api.dwrrah.com/v1/webhooks/endpoints -H "Authorization: Bearer dwr_live_…" -H "Content-Type: application/json" -d '{"url":"https://example.com/dwrrah/webhook","events":["session.booked","payment.succeeded"]}'

The response includes the signing secret (whsec_…) once — store it immediately. The URL must be public HTTPS.

2. Verify every delivery

Before trusting a payload, verify the Dwrrah-Signature header. It's a comma-separated list of v1=<hex> HMAC-SHA256 signatures over Dwrrah-Timestamp + "." + raw_request_body, keyed by your signing secret. Compute the same HMAC and compare. During a secret rotation's 24-hour grace window, the list carries both the new and previous secret's signature.

Common event types

Manage & debug

• Rotate secret — a new secret is returned once; the previous one stays valid for a 24h grace window.
• Test — send a sample event to your endpoint.
• Deliveries — inspect attempts and statuses, and retry failed deliveries.

The Dwrrah MCP server exposes the same capabilities as the REST API — as tools for AI agents — under the same scopes and the same single-academy isolation. Read tools mirror the GET endpoints; write tools are guarded (drafts / explicit confirm) and idempotent.

Server URL: https://mcp.dwrrah.com

Two ways to connect

API key

Create an MCP-enabled key in your dashboard, then point your MCP client at the server with the key as a bearer token. The academy and its scopes come from the key — you never pass an academy_id.

OAuth

Add https://mcp.dwrrah.com as a connector in a client that supports OAuth connectors. You'll be sent to a Dwrrah consent screen to pick one academy and approve scopes. Connections can be reviewed and revoked from your dashboard at any time.

The event stream is the queryable, pull-based companion to Webhooks. Instead of receiving events pushed to your server, you fetch them on demand — ideal for backfills, reconciliation, and audits.

Endpoints: GET /v1/events (list, newest first, cursor-paginated) and GET /v1/events/{id} (single event). Requires the events.read scope. Events are retained for a 60-day window.

What's in the stream

Activity across your academy — courses, lessons, quizzes, sessions, enrollments, certificates, memberships, and payments — plus every internal notification and email sent to students and instructors, each recorded as its specific cause event notification.<type>.

Filtering

Filter by event type. Subscribe to a specific cause, or use notification.* for all notifications. The full list is available from GET /constraints → notification_event_types (see Discovery).

curl "https://api.dwrrah.com/v1/events?type=session.booked&limit=50" -H "Authorization: Bearer dwr_live_…"

Discovery endpoints are agent-native: they let an AI agent (or your own code) learn the shape of an academy — its capabilities, field limits, live structure, and content-block schemas — before making any write. All are read-only.

Endpoints

Readiness

Before publishing, check whether a course is complete: GET /v1/courses/{course_id}/readiness

Block shape

Lesson and page blocks use the canonical shape { "id": "blk_1", "block_type": "text", "sort_order": 0, "config": {} }. Text blocks accept rich HTML.