# NudgeBell: full agent reference

> Plain-text version of https://nudgebell.app/docs for agents and crawlers. NudgeBell is a hosted reminder service that escalates the way the user sets it, across email, WhatsApp, SMS and phone calls, and stops when they acknowledge, with a remote MCP server and a REST API.

What NudgeBell does: once a reminder is created, every step (the call, the retry, the credit deduction, the acknowledgment check) runs on NudgeBell's servers at its scheduled time. Nothing depends on the agent, the user's machine, the network, or the MCP connection staying alive. Positioning: "Escalates the way you set it. Stops when you acknowledge."

Rules for agents:

1. Only the account owner is ever contacted, on their own verified phone and email. There is no recipient parameter; any request naming one (to, phone_number, recipient, at any depth) is rejected with recipient_not_allowed. Do not try to work around this.
2. Acknowledgment is human-only. You can read whether the user pressed 1, tapped the link or clicked the button (get_reminder_status). You can never mark a reminder as done on the user's behalf, and you must not tell the user you did.
3. Prefer pause_reminder over cancel_reminder. Cancel permanently deletes the reminder and its delivery history with no undo; use it only when the user explicitly says delete or stop permanently.
4. The chain is the user's choice: one step or up to five, any channel (email, whatsapp, sms, call) in any order with any gaps. Build what the user asked for and do not add channels or steps they did not ask for; calls and SMS cost far more than email and WhatsApp.
5. Send times in the user's own words as 'YYYY-MM-DDTHH:mm'; it is read in the account's timezone. Do not send a timezone field; the account's timezone always wins.
6. Pass a stable idempotency_key on create if you might retry, so a retry returns the original reminder instead of making a second phone call.
7. Do not quote per-channel credit prices from memory; they vary by destination country. Call get_account for the balance and point the user to https://nudgebell.app/pricing for prices.
8. A create is refused (insufficient_credits, 402) when the balance cannot cover the first step. Nothing is created in that case; tell the user to top up at https://nudgebell.app/settings.

Concepts:

- Reminder: title (max 100 chars), optional description (max 500), trigger_at, recurrence, 1 to 5 steps.
- Step: channel (call | sms | whatsapp | email), message (max 300 chars for call, 500 for the other channels), delay_minutes (0 to 525,600; the first step must be 0; strictly increasing), call_repeat_count (calls only, 1 to 3, default 3).
- Acknowledgment: human-only. Press 1 on the call, tap the link in SMS or WhatsApp, click the button in the email. One acknowledgment cancels the remaining steps of that occurrence.
- Recipients: only the account owner's own verified phone and email. Requests naming a recipient are rejected with recipient_not_allowed.
- Recurrence: none | daily | weekly | monthly | yearly. The whole chain repeats at the same local time in the account's timezone across daylight-saving changes. Monthly and yearly dates on the 29th to 31st move to the last day of a shorter month and stay there.
- Credits: deducted when a step is actually sent, refunded in full on a failed send, refunded minus a small answering-machine-detection fee when a call is unanswered or reaches voicemail. Same rates as the web app; no separate agent billing.

Authentication. Header on every request, REST and MCP:

    Authorization: Bearer nb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Plain HTTP clients may use X-API-Key instead. Keys in the URL are not accepted. Create keys at https://nudgebell.app/settings (Settings, API Keys). A key is shown once. Revoking takes effect immediately; reminders it created keep running.

MCP server:

- URL: https://nudgebell.app/api/v1/mcp
- Transport: Streamable HTTP (JSON-RPC 2.0), protocol 2025-06-18. Up to 20 messages per batch, 256 KB request body.
- Auth: Bearer API key header (above).
- Claude Code: claude mcp add --transport http nudgebell https://nudgebell.app/api/v1/mcp --header "Authorization: Bearer nb_live_YOUR_KEY"
- .mcp.json: { "mcpServers": { "nudgebell": { "type": "http", "url": "https://nudgebell.app/api/v1/mcp", "headers": { "Authorization": "Bearer ${NUDGEBELL_API_KEY}" } } } }
- Cursor (~/.cursor/mcp.json): { "mcpServers": { "nudgebell": { "url": "https://nudgebell.app/api/v1/mcp", "headers": { "Authorization": "Bearer ${env:NUDGEBELL_API_KEY}" } } } }

MCP tools:

- create_reminder(title, trigger_at, steps[], description?, recurrence?, timezone?, idempotency_key?): schedule an escalating chain. Returns the reminder, estimated_credits_per_run and the current balance; idempotent_replay: true marks a replayed create.
- list_reminders(status?, limit?): what is scheduled and how far each chain got.
- get_reminder(reminder_id): full detail of one reminder.
- get_reminder_status(reminder_id, step?): per-step delivered, acknowledged, when.
- pause_reminder(reminder_id): stop the chain, keep the reminder. Resumable from the dashboard.
- cancel_reminder(reminder_id): stop and permanently delete the reminder and its delivery history. No undo.
- get_account(): verified contacts, plan, credits, limits, timezone.

REST API. Base URL: https://nudgebell.app/api/v1

- POST /reminders: create a reminder (1 to 5 steps). Send an Idempotency-Key header for safe retries.
- GET /reminders?status=active|paused|completed&limit=N: list.
- GET /reminders/{id}: full detail.
- GET /reminders/{id}/status?step=N: per-step delivery and acknowledgment status.
- POST /reminders/{id}/pause: pause (reversible from the dashboard).
- POST /reminders/{id}/cancel: delete permanently (terminal).
- GET /account: verified contacts, plan, credits, limits, timezone.
- POST /mcp: the remote MCP endpoint.

Create example (replace the date with a future local time in the account's timezone):

    curl -X POST https://nudgebell.app/api/v1/reminders \
      -H "Authorization: Bearer $NUDGEBELL_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: dentist-<date>" \
      -d '{
        "title": "Call the dentist",
        "trigger_at": "YYYY-MM-DDTHH:mm",
        "recurrence": "none",
        "steps": [
          { "channel": "call",  "message": "Time to call the dentist.", "delay_minutes": 0, "call_repeat_count": 3 },
          { "channel": "sms",   "message": "Still need to call the dentist.", "delay_minutes": 10 },
          { "channel": "email", "message": "Third reminder: call the dentist.", "delay_minutes": 30 }
        ]
      }'

trigger_at without an offset is read as local time in the account's timezone. A full ISO-8601 instant with an offset or Z also works. A conflicting timezone field is ignored; the account's timezone always wins. Create responses include the reminder, estimated_credits_per_run and the current balance.

Status example:

    GET /api/v1/reminders/{id}/status
    => { "acknowledged": false, "chain_position": 1, "chain_length": 3,
         "steps": [ { "step_order": 1, "channel": "call", "status": "sent", "sent_at": "...", "confirmed_at": null }, ... ] }

Retries and idempotency. Send Idempotency-Key (REST) or idempotency_key (MCP) and retries return the original reminder. REST marks a replay with the Idempotent-Replay: true response header; MCP marks it with idempotent_replay: true in the tool result body. Without a key, identical creates within two minutes are collapsed automatically. Keys are kept 90 days, max 255 characters.

Limits:

- Active reminders: Starter 5, Pro 15, Power unlimited (same as the web app).
- delay_minutes: 0 to 525,600 (1 year). trigger_at: in the future, at most 5 years ahead; recurring reminders keep going past that.
- Per key: 10 creates per minute and 60 per hour; 30 cancel-or-pause calls per minute and 300 per hour; 120 reads per minute.
- Up to 10 active API keys per account.
- MCP: up to 20 messages per JSON-RPC batch, 256 KB request body.
- A 429 carries Retry-After and reset_at. A 503 (service_unavailable) means nothing was created; retry shortly.

Errors. Every failure returns { "error": { "code", "message", "details", "docs_url" } }. Over MCP the same object is the tool result with isError: true.

- unauthorized (401): key missing, malformed, or unknown.
- key_revoked (401): key was revoked in Settings.
- plan_limit_reached (403): at the plan's active-reminder limit; details carry plan, active_reminders, limit.
- phone_not_verified (403): a call, sms or whatsapp step was requested but no verified phone is on file.
- recipient_not_allowed (403): the request tried to name a recipient.
- insufficient_credits (402): not enough credits for the first step; details carry required, available, shortfall. No reminder is created.
- invalid_trigger_time (400): trigger_at unparseable, in the past, or more than 5 years ahead.
- channel_unavailable_for_country (400): the verified number cannot take that channel.
- validation_error (400): a field is missing or malformed; details carry the field path.
- reminder_not_found (404): no such reminder on this account (or it was cancelled).
- duplicate_request_in_progress (409): an identical create is already in progress; wait and read your reminders.
- rate_limited (429): per-key limit hit; details carry limit, scope, reset_at; Retry-After is set.
- internal_error (500): nothing was created.
- service_unavailable (503): nothing was created; retry shortly.

Pricing. Every account starts with 25 free credits, no card. Starter $5/month (250 credits per month, 5 active reminders), Pro $15/month (1,200 credits, 15 active), Power $49/month (4,500 credits, unlimited active). Yearly: Starter $48, Pro $144, Power $468 (20% off, about 2.4 months free). Top-up packs: 200 credits $5, 1,000 credits $20, 3,250 credits $65. Unused credits roll over. 1 credit = $0.004; the credit cost of each channel varies by destination country, so do not quote per-channel prices from memory. Authority: https://nudgebell.app/pricing and https://nudgebell.app/refund.

Contact: hello@nudgebell.app

## Docs

- [Agent API and MCP Server](https://nudgebell.app/docs)
- [Short summary](https://nudgebell.app/llms.txt)
- [Pricing](https://nudgebell.app/pricing)