API Reference

Complete API documentation for sending nudges, handling responses, and managing errors.

Sending a Nudge

Every nudge is a single POST request. At minimum, send a status field:

bash

curl https://nudge.sh/$NUDGE_TOKEN -d status="done"

A more complete example with exit code, duration, label, and output:

bash

# Capture everything from a build
START=$(date +%s)
npm run build > /tmp/build.log 2>&1
EXIT_CODE=$?
DURATION=$(( $(date +%s) - $START ))

curl -s https://nudge.sh/$NUDGE_TOKEN \
  -d status="deployed" \
  -d exit_code=$EXIT_CODE \
  -d duration=$DURATION \
  -d label="prod-deploy" \
  --data-urlencode output@/tmp/build.log

Authentication

Your API token goes directly in the URL path: https://nudge.sh/{token}. You can find your token on the dashboard after signing up. For SDK and programmatic integrations, a Bearer token in the Authorization header is also supported.

http

POST /ndg_your_token_here HTTP/1.1
Host: nudge.sh
Content-Type: application/x-www-form-urlencoded

status=done

Store your token safely

Keep your token in an environment variable like NUDGE_TOKEN rather than hardcoding it in scripts. See the Getting Started guide for setup instructions.

Request Parameters

Send a POST request to https://nudge.sh/{token} with any of the following parameters:

Parameter	Type	Description
statusREQUIRED	string	A short status label, e.g. `done`, `failed`, `deployed`. Appears as the headline of your SMS.
exit_code	integer	The exit code of the completed process. `0` is treated as success, anything else as failure.
duration	integer	Elapsed time in seconds. Automatically formatted as human-readable (e.g. "3m 42s") in the SMS.
output	string	Command output or logs (max 50 KB). Viewable via the link in the SMS. Not included in the message body itself.
message	string	Optional custom message body. Overrides the default format entirely.
label	string	A label for the task, e.g. `prod-deploy` or `ml-training`. Helps you identify which job sent the nudge.
stderr	string	Standard error output from the process. Stored alongside `output` and viewable via the nudge detail link.
metadata	JSON string	Arbitrary JSON string of key-value pairs. Useful for attaching structured data like commit SHA, branch name, or environment info.

Response Format

All responses are JSON. A successful nudge returns 201 Created:

201 Created

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "slug": "a8f3k2",
  "url": "https://nudge.sh/r/a8f3k2"
}

Error Responses

401 Unauthorized

{
  "error": "Invalid or missing API token."
}

422 Unprocessable Entity

{
  "error": "Validation failed.",
  "fields": {
    "status": ["The status field is required."]
  }
}

429 Too Many Requests

{
  "error": "Rate limit exceeded. Try again in 42 seconds."
}

Rate Limits

The API allows 60 requests per minute per token. Rate limit status is included in every response via headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per minute (60).
X-RateLimit-Remaining	Requests remaining in the current window.

When the limit is exceeded, the API returns a 429 response. Wait for the window to reset before retrying.

Avoid tight loops

If you are sending nudges from a loop or a batch job, add a small delay between calls. Hitting the rate limit repeatedly may result in temporary throttling beyond the standard window.

URL Token Mode

For the simplest possible integration, you can skip the Authorization header entirely and place your token directly in the URL path:

bash

# Token-in-URL mode -- no Authorization header needed
curl https://nudge.sh/$NUDGE_TOKEN -d status=done

This is equivalent to the full Bearer token request and accepts all the same parameters. It is especially handy for one-liners:

bash

# One-liner after any command
make build && curl https://nudge.sh/$NUDGE_TOKEN -d status=done -d label=build

# With exit code capture
deploy.sh; curl https://nudge.sh/$NUDGE_TOKEN -d status=done -d exit_code=$?

When to use URL token mode

URL token mode is great for quick one-liners and environments where setting headers is cumbersome (e.g. cron jobs, CI/CD configs). For scripts you commit to version control, prefer the Authorization header with an environment variable to avoid leaking your token.

Previous Getting Started Next Shell & Cron