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.

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
groupoptionalstringGroup 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",
    "group": "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",
  "group": "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)
groupoptionalstringFilter by group name
unreadoptionalbooleanFilter by read status (true or false)

Example request

bash
curl https://api.nodkit.dev/api/notifications?limit=10&group=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",
      "group": "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",
  "group": "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
}