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.
| Credential | Looks like | Scope |
|---|---|---|
| Project key | nk_live_… | One project. Its role is admin (read and write) or read_only. |
| Admin key | the ADMIN_API_KEY you set | Every project. Project-scoped routes need x-project-id (or ?projectId=). Also the only key for project management. |
| Dashboard session | nk_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
| Method | Path | Does |
|---|---|---|
| POST | /v1/notify | Send a notification |
| GET | /v1/notifications/{taskId} | Get a task's status |
| DELETE | /v1/notifications/{taskId} | Cancel a scheduled task |
| GET | /v1/notifications/scheduled | List scheduled tasks |
| GET | /v1/notifications/logs | Read the delivery log |
| POST | /v1/users | Create or update a user |
| GET | /v1/users | List users |
| GET | /v1/users/{id} | Get a user |
| GET | /v1/users/{id}/details | Get a user with recent sends |
| PATCH | /v1/users/{id} | Update a user |
| DELETE | /v1/users/{id} | Delete a user |
| POST | /v1/users/{id}/contacts | Add contacts |
| GET | /v1/users/{id}/contacts | List a user's contacts |
| DELETE | /v1/users/{id}/contacts/{channel}/{target} | Remove a contact |
| GET | /v1/users/{id}/preferences | Get preferences |
| PATCH | /v1/users/{id}/preferences | Update preferences |
| GET | /v1/segments | List segments |
| PUT | /v1/templates | Sync templates |
| GET | /v1/templates | List templates |
| GET | /v1/templates/{id} | Get a template |
| DELETE | /v1/templates/{id} | Delete a template |
| POST | /v1/workflows | Create a JSON workflow |
| GET | /v1/workflows | List JSON workflows |
| POST | /v1/workflows/trigger | Trigger a workflow |
| GET | /v1/workflows/instances/{id} | Get an instance |
| DELETE | /v1/workflows/instances/{id} | Cancel an instance |
| POST | /v1/events | Send an event |
| GET | /v1/campaigns | List campaigns |
| GET | /v1/campaigns/{campaign}/stats | Get campaign stats |
| GET | /v1/suppressions | List suppressions |
| POST | /v1/suppressions | Suppress an address |
| DELETE | /v1/suppressions/{channel}/{target} | Remove a suppression |
| GET | /v1/unsubscribe | Unsubscribe page |
| POST | /v1/unsubscribe | Unsubscribe |
| GET | /v1/events/stream | Stream delivery events |
| POST | /{webhookPath} | Receive provider events |
| GET | /{webhookPath} | Verification handshake |
| POST | /v1/projects | Create a project |
| GET | /v1/projects | List projects |
| PATCH | /v1/projects/{id} | Update project limits |
| DELETE | /v1/projects/{id} | Delete a project |
| POST | /v1/projects/{id}/keys | Create an API key |
| GET | /v1/projects/{id}/keys | List API keys |
| DELETE | /v1/projects/{id}/keys/{keyId} | Revoke an API key |
| POST | /v1/auth/login | Log in |
| GET | /v1/auth/me | Current session |
| POST | /v1/auth/logout | Log out |
| GET | /live | Liveness |
| GET | /ready | Readiness |
| GET | /health | Health |
| GET | /metrics | Prometheus metrics |
| GET | /v1/system/health | System health |
| GET | /v1/system/metrics | System metrics |
| GET | /v1/dlq | List dead letters |
| POST | /v1/dlq/replay | Replay a dead letter |
| DELETE | /v1/dlq/{id} | Delete a dead letter |