Skip to main content

​
Endpoint

POST /api/notify

​
Headers

HeaderRequiredDescription
X-API-KeyYesYour API key
Content-TypeYesapplication/json
Idempotency-KeyNoUnique string to prevent duplicate processing. Same key within 24 hours returns the cached response.

​
Request body

​
user_emails
string[]
required
Email addresses of the recipients. Must match users registered in your NextKS organization. Maximum 50 entries.
​
message
string
required
The message text to send. Maximum 4000 characters. Supports markdown formatting — see Message formatting below.
​
external_reference_id
string
An optional identifier from your system (e.g., ticket ID, deployment ID). Maximum 200 characters. Returned in status queries and callbacks for correlation. Only meaningful when used with response_request.
​
response_request
object
Include this field to send an interactive notification with response buttons. See Interactive Notifications for the full specification.

​
Response

​
Fire-and-forget (no response_request)

{
  "status": "ok",
  "notification_id": "notif_a1b2c3d4e5f6"
}
The notification_id is a unique identifier for tracking this notification.

​
Interactive (with response_request)

{
  "status": "ok",
  "request_id": "req_a1b2c3d4e5f6..."
}
If you provided a callback_url, the response also includes a callback_secret for verifying callback signatures — see Callbacks. 
{
  "status": "ok",
  "request_id": "req_a1b2c3d4e5f6...",
  "callback_secret": "dGhpc19pc19hX3NlY3JldA..."
}
The request_id can be used to check response status.

​
Errors

StatusDetails
400Invalid request body (malformed JSON, missing fields, validation errors)
401Invalid API key
422Valid request but business rule violation (e.g., unknown user emails)
429Rate limit exceeded — see Rate Limits
500Delivery failure
{
  "status": "error",
  "details": "Unknown user emails: nobody@example.com"
}

​
Example

curl -X POST https://app.nextks.com/api/notify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "user_emails": ["alice@company.com", "bob@company.com"],
    "message": "Build #1847 completed successfully.\nAll 342 tests passed."
  }'

​
Message formatting

The message field supports markdown that renders natively on both Slack and Teams:
SyntaxResult
*bold*bold
_italic_italic
`code`code
```code block```Code block
- itemBullet list
[Link text](https://...)Clickable link
\nLine break
Links are automatically converted to each platform’s native format — standard markdown links work in both Slack and Teams.