---
title: "Send a notification to yourself"
method: POST
path: "/api/notifications/send"
tags: ["Notifications"]
---

# Send a notification to yourself

`POST /api/notifications/send`

## Request

- Base URL: `https://api.hiyd.ai`
- URL: `https://api.hiyd.ai/api/notifications/send`
- Auth: HTTP bearer

Queues the notification in the push outbox and, unless schedule_at is in the future, delivers it in the request to every registered installation of the user (falling back to the legacy fcm_token). Future-scheduled notifications are delivered by the dispatcher at their time. schedule_at may be at most 7 days ahead, and a user may have at most 10 notifications from this endpoint waiting to be sent.

## Request body

- object
  - `title` string, required
  - `message` string, required
  - `type` 'health_alert' | 'goal_reminder' | 'achievement' | 'social' | 'system', required
  - `priority` 'low' | 'medium' | 'high' | 'urgent'
  - `schedule_at` string, date-time: Optional future delivery time, at most 7 days ahead
  - `metadata` object

## Response `201`

Notification row created. Delivery outcome is in `push`; `notification.status` is the row's status afterwards (pending when scheduled or deferred, sent, failed, skipped, suppressed, ...).

- object
  - `notification` Notification
    - `id` string, uuid
    - `user_id` string, uuid
    - `title` string
    - `message` string
    - `type` 'health_alert' | 'goal_reminder' | 'achievement' | 'social' | 'system' | 'marketing'
    - `priority` 'low' | 'medium' | 'high' | 'urgent'
    - `status` 'pending' | 'sending' | 'sent' | 'delivered' | 'read' | 'failed' | 'cancelled' | 'expired' | 'suppressed' | 'skipped'
    - `deep_link` string, nullable: App route to open on tap, e.g. hiyd://recommendation
    - `scheduled_at` string, date-time
    - `sent_at` string, date-time
    - `read_at` string, date-time
    - `metadata` object
    - `created_at` string, date-time
  - `push` object: Always the same shape.
    - `attempted` boolean: true when FCM was called
    - `sent` boolean
    - `reason` string, nullable: null when sent; 'scheduled'; a delivery reason such as 'no_tokens', 'permission_denied', 'user_disabled' or 'paused'; or an FCM messaging/* code
    - `message_id` string, nullable
    - `token_cleared` boolean: true when FCM reported a stored token dead and it was removed
    - `status_recorded` boolean: false only if the push was sent but the row could not be updated

## Other responses

- `429`: too_many_waiting: 10 notifications from this endpoint are already waiting to be sent

---

[API](https://skmtc.dev/hiyd/apis/hiyd-backend-api.md) - [All operations](https://skmtc.dev/hiyd/apis/hiyd-backend-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hiyd/apis/hiyd-backend-api/revisions/23598d347e1b?raw)