Docs
Nudgio has one job: an agent asks, a human answers, the agent gets the answer. Everything below is available over MCP and over REST with the same credentials.
1. Connect an agent
Claude and ChatGPT (no key)
Add a custom connector with the URL https://nudgio.co.uk/mcp. You are sent here to sign in and approve it, and choose the name its questions appear under.
Claude Code and other MCP clients
Create an agent on the Agents page, copy its key, then:
claude mcp add --transport http nudgio https://nudgio.co.uk/mcp \
--header "Authorization: Bearer ndg_your_agent_key"
REST
curl https://nudgio.co.uk/api/v1/requests \
-H "Authorization: Bearer ndg_your_agent_key" \
-H "Content-Type: application/json" \
-d '{"title":"Deploy to production?","options":[{"id":"yes","label":"Deploy"},{"id":"no","label":"Not yet"}],"wait":55}'
2. Tools
| Tool | REST | Purpose |
|---|---|---|
ask | POST /api/v1/requests | Create a request. Returns the answer if it arrives within wait seconds, otherwise status: "pending" and a request_id. |
wait_for | GET /api/v1/requests/:id/wait?timeout=55 | Block up to 55 seconds on an existing request. Call again while it is pending. |
get | GET /api/v1/requests/:id | Current state, without waiting. |
list | GET /api/v1/requests?state= | This agent's recent requests. |
cancel | POST /api/v1/requests/:id/cancel | Withdraw a pending request. |
notify | POST /api/v1/notifications | A message that needs no answer. |
ask arguments
| Field | Notes |
|---|---|
title | Required. Up to 120 characters. |
body | Longer detail, such as the draft being approved. |
options | Up to four: {id, label, style}. style is default or destructive. |
allow_text | Let the human type a reply. Defaults to true when there are no options. |
priority | normal or time-sensitive. |
expires_in | Seconds until the request expires. Default 86400, maximum 7 days. |
context | Any JSON object. Returned with the answer and in webhooks, so your agent needs no state of its own. |
wait | 0 to 55 seconds to block for the answer. |
idempotency_key | The same key within 24 hours returns the existing request. Over REST you can send an Idempotency-Key header instead. |
Result
{
"request_id": "req_…",
"status": "answered", // pending | answered | expired | cancelled
"answer": { "option_id": "send", "option_label": "Send", "text": "change the second line" },
"context": { "draftId": 7 },
"created_at": "…", "expires_at": "…", "answered_at": "…"
}
3. Waiting for a human
People take longer than a tool call is allowed to. A single call blocks for at most 55 seconds; for longer waits call wait_for in a loop, or set a webhook. An agent only hears the answer if it is still running, so this suits background agents, loops and workflows. A chat that has ended its turn will see the answer when it next calls get or wait_for.
Delivery to a person is never guaranteed, so write the agent to handle expired as "no answer".
4. Webhooks
Set a URL per agent on the Agents page. Nudgio POSTs JSON when a request is request.answered, request.expired or request.cancelled, and retries after 1 minute, 5 minutes, 30 minutes and 2 hours if you do not return a 2xx.
POST /your-endpoint
X-Nudgio-Event: request.answered
X-Nudgio-Signature: t=1795337083,v1=5f2c…
{ "id": "whd_…", "event": "request.answered", "created_at": "…", "request": { …same shape as the result above… } }
Verify it: compute HMAC-SHA256 of t + "." + rawBody with your signing secret, compare with v1, and reject timestamps more than five minutes old.
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return Math.abs(Date.now() / 1000 - Number(t)) < 300
&& expected.length === v1.length
&& timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
5. Limits
Each agent can create 60 requests an hour and 300 a day. Beyond that the API returns 429 with a Retry-After header. Request bodies are deleted after 30 days; the audit record of who answered and when is kept.
