API Documentation

Everything you need to send push notifications to your phone with a single API call.

Getting Started

Get up and running with Nodkit in under a minute.

  1. 1Download the Nodkit app from the App Store.
  2. 2Sign in with your Apple ID.
  3. 3Go to Settings in the app and copy your API key.

That's it. You're ready to send notifications.

Authentication

All API requests require your API key in the Authorization header using Bearer token authentication.

Header
Authorization: Bearer nk_your_api_key_here

Your API key starts with nk_ and can be found in the Settings screen of the Nodkit app. Keep it secret -- anyone with your key can send notifications to your devices.

Command-line tool

The Nodkit CLI lets you send notifications without writing any HTTP code. It's a single static binary — no runtime required.

Install

bash
curl -fsSL https://api.nodkit.dev/install.sh | sh

Supported on macOS and Linux (amd64 and arm64). The binary is installed to ~/.local/bin/nodkit.

Usage

bash
# One-time: paste your API key
nodkit login

# Send a notification
nodkit send "Build finished"

# With a body, channel, and high priority
nodkit send "Deploy complete" -b "v2.3.1 shipped" -c deploys -p high

# Pipe stdin into the body
echo "all green" | nodkit send "CI passed"

# Read body from a file
nodkit send "Daily report" -b @./report.md

# List recent notifications
nodkit list --unread --limit 10

In CI, set NODKIT_API_KEY as a secret instead of running nodkit login — the env var takes precedence over the saved config file.

Send a Notification

POST/api/send

Send a push notification to all your registered devices.

Request body

ParameterTypeDescription
titlerequiredstringNotification title
subtitleoptionalstringNotification subtitle
bodyoptionalstringNotification body text
priorityoptionalstringnormal (default) or high
channeloptionalstringChannel name for organizing notifications

Example request

bash
curl -X POST https://api.nodkit.dev/api/send \
  -H "Authorization: Bearer nk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy Complete",
    "subtitle": "production",
    "body": "v2.3.1 deployed successfully to all 3 instances",
    "priority": "normal",
    "channel": "deploys"
  }'

Success response 201 Created

json
{
  "id": "ntf_abc123def456",
  "title": "Deploy Complete",
  "subtitle": "production",
  "body": "v2.3.1 deployed successfully to all 3 instances",
  "priority": "normal",
  "channel": "deploys",
  "read": false,
  "createdAt": "2026-04-04T12:00:00.000Z"
}

List Notifications

GET/api/notifications

Retrieve a paginated list of your notifications.

Query parameters

ParameterTypeDescription
limitoptionalintegerNumber of results (default: 30, max: 100)
cursoroptionalstringCursor for pagination (from previous response)
channeloptionalstringFilter by channel name
unreadoptionalbooleanFilter by read status (true or false)

Example request

bash
curl https://api.nodkit.dev/api/notifications?limit=10&channel=deploys \
  -H "Authorization: Bearer nk_your_api_key_here"

Response 200 OK

json
{
  "notifications": [
    {
      "id": "ntf_abc123def456",
      "title": "Deploy Complete",
      "subtitle": "production",
      "body": "v2.3.1 deployed successfully to all 3 instances",
      "priority": "normal",
      "channel": "deploys",
      "read": false,
      "createdAt": "2026-04-04T12:00:00.000Z"
    }
  ],
  "cursor": "eyJpZCI6Im50Zl9hYmMxMjMifQ",
  "hasMore": true
}

Get Notification

GET/api/notifications/{id}

Retrieve a single notification by its ID.

Example request

bash
curl https://api.nodkit.dev/api/notifications/ntf_abc123def456 \
  -H "Authorization: Bearer nk_your_api_key_here"

Response 200 OK

json
{
  "id": "ntf_abc123def456",
  "title": "Deploy Complete",
  "subtitle": "production",
  "body": "v2.3.1 deployed successfully to all 3 instances",
  "priority": "normal",
  "channel": "deploys",
  "read": false,
  "createdAt": "2026-04-04T12:00:00.000Z"
}

Mark as Read

PATCH/api/notifications/{id}/read

Mark a notification as read or unread.

Request body

ParameterTypeDescription
readrequiredbooleantrue to mark as read, false to mark as unread

Example request

bash
curl -X PATCH https://api.nodkit.dev/api/notifications/ntf_abc123def456/read \
  -H "Authorization: Bearer nk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"read": true}'

Response 200 OK

json
{
  "id": "ntf_abc123def456",
  "read": true
}

Delete Notification

DELETE/api/notifications/{id}

Permanently delete a notification.

Example request

bash
curl -X DELETE https://api.nodkit.dev/api/notifications/ntf_abc123def456 \
  -H "Authorization: Bearer nk_your_api_key_here"

Response 204 No Content

Returns an empty response on success.

Rate Limits

API requests are rate-limited per endpoint to ensure fair usage and service stability.

EndpointLimit
POST /api/send60 requests / minute
GET /api/notifications120 requests / minute
GET /api/notifications/{id}60 requests / minute
PATCH /api/notifications/{id}/read60 requests / minute
DELETE /api/notifications/{id}60 requests / minute

When you exceed a rate limit, the API returns a 429 Too Many Requests response. Wait before retrying. The response includes a Retry-After header indicating how many seconds to wait.

Errors

The API uses standard HTTP status codes to indicate success or failure.

StatusMeaningDescription
201CreatedNotification sent successfully
200OKRequest succeeded
204No ContentDeletion succeeded
400Bad RequestInvalid request body or missing required fields
401UnauthorizedInvalid or missing API key
404Not FoundNotification not found
429Too Many RequestsRate limit exceeded
500Server ErrorSomething went wrong on our end

Error response format

json
{
  "error": "Invalid or missing API key",
  "code": 401
}