Send Notification

Endpoint

POST /api/notify

Headers

Header	Required	Description
`X-API-Key`	Yes	Your API key
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Unique string to prevent duplicate processing. Same key within 24 hours returns the cached response.

Request body

string[]

required

Email addresses of the recipients. Must match users registered in your NextKS organization. Maximum 50 entries.

string

required

The message text to send. Maximum 4000 characters. Supports markdown formatting — see Message formatting below.

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.

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

Status	Details
`400`	Invalid request body (malformed JSON, missing fields, validation errors)
`401`	Invalid API key
`422`	Valid request but business rule violation (e.g., unknown user emails)
`429`	Rate limit exceeded — see Rate Limits
`500`	Delivery 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."
  }'

const response = await fetch('https://app.nextks.com/api/notify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY',
  },
  body: JSON.stringify({
    user_emails: ['alice@company.com', 'bob@company.com'],
    message: 'Build #1847 completed successfully.\nAll 342 tests passed.',
  }),
})

const data = await response.json()
console.log(data.notification_id) // "notif_a1b2c3d4e5f6"

import requests

response = requests.post(
    "https://app.nextks.com/api/notify",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "YOUR_API_KEY",
    },
    json={
        "user_emails": ["alice@company.com", "bob@company.com"],
        "message": "Build #1847 completed successfully.\nAll 342 tests passed.",
    },
)

data = response.json()
print(data["notification_id"])  # "notif_a1b2c3d4e5f6"

Message formatting

The message field supports markdown that renders natively on both Slack and Teams:

Syntax	Result
`bold`	bold
`_italic_`	italic
`code`	`code`
```code block```	Code block
`- item`	Bullet list
`[Link text](https://...)`	Clickable link
`\n`	Line break

Links are automatically converted to each platform’s native format — standard markdown links work in both Slack and Teams.

​Endpoint

​Headers

​Request body

​Response

​Fire-and-forget (no response_request)

​Interactive (with response_request)

​Errors

​Example

​Message formatting

Endpoint

Headers

Request body

Response

Fire-and-forget (no `response_request`)

Interactive (with `response_request`)

Errors

Example

Message formatting