> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nextks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Notification

> Send a message to one or more users via the NextKS bot.

## 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

<ParamField body="user_emails" type="string[]" required>
  Email addresses of the recipients. Must match users registered in your NextKS organization. Maximum 50 entries.
</ParamField>

<ParamField body="message" type="string" required>
  The message text to send. Maximum 4000 characters. Supports markdown formatting — see [Message formatting](#message-formatting) below.
</ParamField>

<ParamField body="external_reference_id" type="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`.
</ParamField>

<ParamField body="response_request" type="object">
  Include this field to send an **interactive notification** with response buttons. See [Interactive Notifications](/api-reference/interactive-notifications) for the full specification.
</ParamField>

## Response

### Fire-and-forget (no `response_request`)

```json theme={null}
{
  "status": "ok",
  "notification_id": "notif_a1b2c3d4e5f6"
}
```

The `notification_id` is a unique identifier for tracking this notification.

### Interactive (with `response_request`)

```json theme={null}
{
  "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](/api-reference/callbacks).

```json theme={null}
{
  "status": "ok",
  "request_id": "req_a1b2c3d4e5f6...",
  "callback_secret": "dGhpc19pc19hX3NlY3JldA..."
}
```

The `request_id` can be used to [check response status](/api-reference/check-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](/api-reference/rate-limits)      |
| `500`  | Delivery failure                                                         |

```json theme={null}
{
  "status": "error",
  "details": "Unknown user emails: nobody@example.com"
}
```

## Example

<CodeGroup>
  ```bash cURL theme={null}
  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."
    }'
  ```

  ```typescript Node.js theme={null}
  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"
  ```

  ```python Python theme={null}
  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"
  ```
</CodeGroup>

## 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     |

<Note>
  Links are automatically converted to each platform's native format — standard markdown links work in both Slack and Teams.
</Note>