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

ToolRESTPurpose
askPOST /api/v1/requestsCreate a request. Returns the answer if it arrives within wait seconds, otherwise status: "pending" and a request_id.
wait_forGET /api/v1/requests/:id/wait?timeout=55Block up to 55 seconds on an existing request. Call again while it is pending.
getGET /api/v1/requests/:idCurrent state, without waiting.
listGET /api/v1/requests?state=This agent's recent requests.
cancelPOST /api/v1/requests/:id/cancelWithdraw a pending request.
notifyPOST /api/v1/notificationsA message that needs no answer.

ask arguments

FieldNotes
titleRequired. Up to 120 characters.
bodyLonger detail, such as the draft being approved.
optionsUp to four: {id, label, style}. style is default or destructive.
allow_textLet the human type a reply. Defaults to true when there are no options.
prioritynormal or time-sensitive.
expires_inSeconds until the request expires. Default 86400, maximum 7 days.
contextAny JSON object. Returned with the answer and in webhooks, so your agent needs no state of its own.
wait0 to 55 seconds to block for the answer.
idempotency_keyThe 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.