Star
API reference

API reference

Every notifkit endpoint, request and response. The REST API is what the TypeScript client and the MCP server call, so anything here works from any language.

Base URL

Endpoints live on the server running the api service, on port 3000 by default. Everything is under /v1 except the probes (/live, /ready, /health, /metrics).

curl http://localhost:3000/v1/templates -H "Authorization: Bearer $NK_KEY"

Authentication

Send a key as Authorization: Bearer <key> or as x-api-key: <key>. A ?token= query parameter also works, which is how a browser EventSource reaches the event stream.

CredentialLooks likeScope
Project keynk_live_…One project. Its role is admin (read and write) or read_only.
Admin keythe ADMIN_API_KEY you setEvery project. Project-scoped routes need x-project-id (or ?projectId=). Also the only key for project management.
Dashboard sessionnk_sess_…Same as the admin key. Users with the superadmin or admin role can write. Other roles are read-only.

Keys are stored as SHA-256 hashes, so a key is shown once, when it's created.

Requests and responses

Bodies are JSON, up to 5 MB. Responses are JSON, except the unsubscribe pages (HTML), /metrics (Prometheus text) and the event stream (text/event-stream). Every error has an error code, and most have a message.

Errors every route can return

Each endpoint lists these under Common errors, with the ones that apply to it.

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "bad_request",
  "message": "x-project-id header or projectId query param required when using admin token"
}
{
  "error": "forbidden",
  "message": "API key is read-only"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "malformed_json",
  "message": "malformed_json"
}
{
  "error": "payload_too_large",
  "message": "payload_too_large"
}
{
  "error": "internal_error"
}

An unknown path answers 404:

{
  "error": "not_found"
}

Validation errors list each failing field. path is dot-joined, and empty when the whole body is wrong:

{
  "error": "validation_error",
  "issues": [
    {
      "path": "template",
      "message": "Invalid input: expected string, received undefined"
    }
  ]
}

Rate limits

Each project gets 600 requests a minute by default, counted over a sliding 60-second window. Change it per project with rateLimitRpm on PATCH /v1/projects/:id. Requests made with the admin key or a session get 6,000 a minute. Project management routes aren't rate-limited.

Two public routes are limited per client IP instead: login at 10 a minute and unsubscribe at 60 a minute.

Idempotency

Send x-idempotency-key on POST /v1/notify and a repeat of the same key within 24 hours is dropped. The repeat still answers 202, so retrying is safe. Derive the key from your own data (an order id, the hour a cron job covers), not from a random value.

Pagination

List endpoints that can grow take limit and return nextCursor. Pass it back as cursor for the next page. nextCursor is null on the last page. Limits are clamped to each endpoint's maximum.

CORS

Project routes allow any browser origin. The session routes (/v1/auth, /v1/projects, /v1/system, /v1/dlq) allow only the origins in CORS_ORIGIN.

All endpoints

MethodPathDoes
POST/v1/notifySend a notification
GET/v1/notifications/{taskId}Get a task's status
DELETE/v1/notifications/{taskId}Cancel a scheduled task
GET/v1/notifications/scheduledList scheduled tasks
GET/v1/notifications/logsRead the delivery log
POST/v1/usersCreate or update a user
GET/v1/usersList users
GET/v1/users/{id}Get a user
GET/v1/users/{id}/detailsGet a user with recent sends
PATCH/v1/users/{id}Update a user
DELETE/v1/users/{id}Delete a user
POST/v1/users/{id}/contactsAdd contacts
GET/v1/users/{id}/contactsList a user's contacts
DELETE/v1/users/{id}/contacts/{channel}/{target}Remove a contact
GET/v1/users/{id}/preferencesGet preferences
PATCH/v1/users/{id}/preferencesUpdate preferences
GET/v1/segmentsList segments
PUT/v1/templatesSync templates
GET/v1/templatesList templates
GET/v1/templates/{id}Get a template
DELETE/v1/templates/{id}Delete a template
POST/v1/workflowsCreate a JSON workflow
GET/v1/workflowsList JSON workflows
POST/v1/workflows/triggerTrigger a workflow
GET/v1/workflows/instances/{id}Get an instance
DELETE/v1/workflows/instances/{id}Cancel an instance
POST/v1/eventsSend an event
GET/v1/campaignsList campaigns
GET/v1/campaigns/{campaign}/statsGet campaign stats
GET/v1/suppressionsList suppressions
POST/v1/suppressionsSuppress an address
DELETE/v1/suppressions/{channel}/{target}Remove a suppression
GET/v1/unsubscribeUnsubscribe page
POST/v1/unsubscribeUnsubscribe
GET/v1/events/streamStream delivery events
POST/{webhookPath}Receive provider events
GET/{webhookPath}Verification handshake
POST/v1/projectsCreate a project
GET/v1/projectsList projects
PATCH/v1/projects/{id}Update project limits
DELETE/v1/projects/{id}Delete a project
POST/v1/projects/{id}/keysCreate an API key
GET/v1/projects/{id}/keysList API keys
DELETE/v1/projects/{id}/keys/{keyId}Revoke an API key
POST/v1/auth/loginLog in
GET/v1/auth/meCurrent session
POST/v1/auth/logoutLog out
GET/liveLiveness
GET/readyReadiness
GET/healthHealth
GET/metricsPrometheus metrics
GET/v1/system/healthSystem health
GET/v1/system/metricsSystem metrics
GET/v1/dlqList dead letters
POST/v1/dlq/replayReplay a dead letter
DELETE/v1/dlq/{id}Delete a dead letter