Notifications

Notifications are the summaries and alerts Day Planner writes for you — a morning plan, a warning about a deadline at risk. Every endpoint acts only on your own notifications and needs an API key or a signed-in session — see API keys. Requests without one get 401 Unauthorized; error responses carry an error message.

List notifications

Returns your 50 most recent notifications and your unread count.

GET /api/notifications

It takes no parameters.

Response

200 OK with the notifications and the unread count.

{
  "notifications": [
    {
      "id": "d4a7c1e9-6b2f-4d8a-9e5c-0f3b6a2c8d17",
      "userId": "b1d4e7a0-2c5f-4b8e-9a1d-6c3f0e2b5a78",
      "type": "morning_summary",
      "title": "Good morning! Here's your plan for Thursday, 1 October",
      "body": "3 tasks scheduled. 1 hard-deadline task at risk.",
      "read": false,
      "metadata": {
        "scheduledTasks": 3,
        "atRiskCount": 1,
        "atRiskTaskIds": ["c9f2a5d8-3e6b-4a1c-9d7f-2b5e8a0c3f64"]
      },
      "createdAt": "2026-09-30T23:02:10.441Z"
    }
  ],
  "unreadCount": 1
}

Notifications come newest first; metadata holds whatever the generator recorded, such as the task ids behind an alert.

Errors

• 401 Unauthorized — no valid API key or session.

Generate notifications

Generates a morning summary or an at-risk deadline alert. The scheduler calls this after a run, and you can call it yourself.

POST /api/notifications

The body picks which one to generate.

Body fields

Name	Type	Required	Description
type	string	Yes	morning_summary or at_risk

morning_summary writes one summary per day in your timezone covering the day’s blocks and at-risk tasks; calling it again on the same day adds nothing. at_risk writes one at_risk_deadline alert listing every task due within 24 hours that has no active time block, and skips tasks an alert already covered in the last six hours.

Response

200 OK with what was generated and the new unread count.

{
  "generated": 2,
  "unreadCount": 3
}

For at_risk, generated counts the tasks the alert covers and is 0 when nothing is new; for morning_summary it is always 1.

Errors

• 400 Bad Request — type is missing or neither morning_summary nor at_risk; details names the fields.
• 401 Unauthorized — no valid API key or session.

Mark all notifications as read

Marks every unread notification as read.

PATCH /api/notifications

It takes no body.

Response

200 OK with how many notifications changed.

{ "markedRead": 4 }

Only notifications that were unread are counted.

Errors

• 401 Unauthorized — no valid API key or session.

Mark a notification as read

Marks a single notification as read.

POST /api/notifications/read

The body names the notification.

Body fields

Name	Type	Required	Description
notificationId	string	Yes	The notification’s id

Response

200 OK once the notification is read.

{ "success": true }

Calling this for an already-read notification succeeds without changing anything.

Errors

• 400 Bad Request — notificationId is missing or not a UUID; details names the fields.
• 404 Not Found — no notification of that id belongs to you; the error message is Notification not found.
• 401 Unauthorized — no valid API key or session.

Example: generate a morning summary

Ask for today’s summary straight away.

curl -X POST https://tasks.example.com/api/notifications \
  -H "Authorization: Bearer dp_change-me" \
  -H "Content-Type: application/json" \
  -d '{"type":"morning_summary"}'

The response is 200 OK with generated set to 1; read the summary through the List notifications response.

See also

• Planner: run the planner before generating at-risk alerts
• run_scheduler: the scheduler run that generates alerts for you
• API keys: authenticate REST calls