REST API reference
Available v1 REST endpoints, parameters and required permissions.
REST API v1
Base URL: https://app.nudgeforme.com/api/v1 (Global) or https://europe.nudgeforme.com/api/v1 (EU).
Use Authorization: Bearer YOUR_NUDGE_API_KEY (developer keys) or a valid Nudge OAuth access token. JSON request/response bodies are used. GET parameters go in the query string, POST parameters in a JSON object.
| Method | Path | Scope |
|---|---|---|
| GET | /workspaces | nudge.mailboxes.read |
| GET | /mailboxes | nudge.mailboxes.read |
| GET | /conversations | nudge.conversations.read |
| GET | /opportunities | nudge.conversations.read |
| GET | /conversations/details | nudge.conversations.read |
| GET | /followups/status | nudge.conversations.read |
| POST | /conversations/watch | nudge.conversations.write |
| POST | /drafts | nudge.drafts.write |
| POST | /followups/pause | nudge.followups.write |
GET workspaces
Optional query: organizationId. Returns workspaces accessible to the authenticated account. Workspace-scoped keys cannot expand their authorization by changing organization IDs.
GET mailboxes
Optional query: organizationId. Returns accessible connected mailboxes, including mailbox IDs used by other operations.
GET conversations
Required: mailboxId. Optional: organizationId, search (up to 120 characters), limit (1–50, default 20). Finds conversations previously sent from the specified mailbox.
GET opportunities
Optional: organizationId, workspaceId, limit (1–100, default 40). Returns current follow-up opportunities. Workspace-limited developer keys are restricted to their configured workspace.
GET conversations/details
Required: threadId. Optional: organizationId. Returns status, recipient/subject and key follow-up timestamps for a watched thread. Full email bodies are not returned.
GET followups/status
Required: threadId. Optional: organizationId. Reads a watched thread's follow-up state.
POST conversations/watch
Required JSON: mailboxId, providerThreadId. Supply a unique requestId in the body or an Idempotency-Key header. Optional: organizationId. This adds a previously sent thread to monitoring; it does not send a message.
POST drafts
Required JSON: threadId. Optional: organizationId, research (boolean). Supply a unique request identifier. This creates a follow-up draft for human review, never sends. Research depends on your plan and configured integrations.
curl -X POST "https://app.nudgeforme.com/api/v1/drafts" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: draft-demo-20261110-001" \
-d '{"threadId":"EXISTING_WATCHED_THREAD_ID","research":false}'
POST followups/pause
Required JSON: threadId. Supply a unique requestId or Idempotency-Key header. Stops further follow-up monitoring for that thread.
Write-request idempotency
For all three POST endpoints, the request identifier must contain 8–100 letters, digits, underscores, periods, colons or hyphens. The server rejects reuse of an identifier for a different operation, and rejects concurrent or uncertain retries. Read back the thread status before creating a new write request after a timeout.
Error handling
Errors return JSON with error and message. Common statuses: 400 invalid input, 401 missing/invalid credentials, 403 insufficient scope or workspace access, 404 unknown endpoint/resource, 409 conflicting/unsafe operation, 429 API-key rate limit, 500 unexpected server error.
A developer key cannot call /mcp. No REST endpoint in this version sends email or changes scheduled cadence.
See Safe drafting workflow and Authentication.