# Send a notification

> POST /n/{publicId}: send a notification to Alphorn with JSON or plain text. Request body, Bearer API key auth, status codes, and response format.

Source: https://docs.alphorn.dev/endpoints/send-notification/

OpenAPI 3.1 specification (with all referenced components): https://docs.alphorn.dev/openapi.json

## POST /n/{publicId}

```json
{
  "operationId": "sendNotification",
  "tags": [
    "Notifications"
  ],
  "summary": "Send a notification",
  "description": "Accepts a notification and queues it for delivery to every enabled channel of the webhook whose filter matches. The response returns as soon as the notification is stored; it does not wait for delivery.\n\nThe body can be a JSON object (any fields; `title`, `message`, `priority`, and `tags` are recognized, others are guessed from common field names or mapped with webhook templates), a Slack-compatible payload, or plain text. A body starting with `{` is parsed as JSON even without a JSON `Content-Type`.\n\nChecks run in this order and the first failure decides the response: 404, 401, 403, 508, 429, 413, 400.",
  "security": [
    {
      "bearerAuth": []
    },
    {}
  ],
  "parameters": [
    {
      "name": "publicId",
      "in": "path",
      "required": true,
      "description": "The webhook's public ID, the last segment of its Endpoint URL.",
      "schema": {
        "type": "string",
        "examples": [
          "V1StGXR8_Z5jdHi6B-myT"
        ]
      }
    },
    {
      "name": "X-Title",
      "in": "header",
      "required": false,
      "description": "Plain-text bodies only: notification title.",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "X-Priority",
      "in": "header",
      "required": false,
      "description": "Plain-text bodies only: priority from 1 to 5.",
      "schema": {
        "type": "string",
        "examples": [
          "4"
        ]
      }
    },
    {
      "name": "X-Tags",
      "in": "header",
      "required": false,
      "description": "Plain-text bodies only: comma-separated tags.",
      "schema": {
        "type": "string",
        "examples": [
          "deploy,production"
        ]
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Notification"
        },
        "examples": {
          "agent": {
            "summary": "AI agent needs input",
            "value": {
              "title": "Claude Code - my-app",
              "message": "Needs permission to run the database migration",
              "priority": 4,
              "tags": [
                "ai-agent",
                "claude-code",
                "permission"
              ]
            }
          }
        }
      },
      "text/plain": {
        "schema": {
          "type": "string",
          "description": "The notification message. Use the X-Title, X-Priority, and X-Tags headers for the other fields."
        },
        "example": "Backup finished in 42s"
      }
    }
  },
  "responses": {
    "201": {
      "description": "Notification accepted and queued for delivery.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "messageId"
            ],
            "properties": {
              "messageId": {
                "type": "string",
                "description": "ID of the stored message."
              }
            }
          },
          "example": {
            "messageId": "0199b2f4-3c1e-7a8d-9f20-5d4c3b2a1e0f"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/InvalidBody"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Disabled"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "413": {
      "$ref": "#/components/responses/PayloadTooLarge"
    },
    "429": {
      "$ref": "#/components/responses/QuotaExceeded"
    },
    "508": {
      "$ref": "#/components/responses/LoopDetected"
    }
  }
}
```