Skip to content

API Reference

Jump to bottom
dbwg2009 edited this page May 4, 2026 · 1 revision

API Reference

Noted uses Next.js server actions for all mutations. The only HTTP API routes are for auth, the cron job, and the iCal feed.

Cron — daily reminders

POST /api/cron/reminders

Runs the daily reminder job. Finds all due reminders, builds a budget-aware shortlist for each person, and sends digest emails via Resend.

Authentication: Bearer token in the Authorization header.

Authorization: Bearer <CRON_SECRET>

Responses:

Status Meaning
200 Job ran successfully. Body: { sent: N }
401 Missing or invalid CRON_SECRET.
500 Internal error (check server logs).

Idempotency: Safe to call multiple times. Each Reminder row tracks last_sent_for_year — the same reminder won't fire twice in the same calendar year.

Docker cron sidecar: The cron service in docker-compose.yml runs this automatically:

curl -X POST \
  -H "Authorization: Bearer $CRON_SECRET" \
  http://app:3000/api/cron/reminders

It fires every CRON_INTERVAL_SECONDS (default 86400 — once daily).

Manual trigger (dev):

curl -X POST \
  -H "Authorization: Bearer YOUR_CRON_SECRET" \
  http://localhost:3000/api/cron/reminders

Or use the "Send test now" button on any person's detail page.

iCal feed

GET /api/ical/[token]/route

Returns a .ics file containing all birthdays for the authenticated user.

Authentication: The [token] path segment is the user's ical_token (a UUID stored in the users table). No session cookie required — the token is the secret.

Example URL:

http://localhost:3000/api/ical/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response headers:

Content-Type: text/calendar; charset=utf-8
Content-Disposition: attachment; filename="birthdays.ics"
Cache-Control: private, max-age=3600, stale-while-revalidate=86400

Notes:

  • The token is auto-generated on account creation.
  • Reset it from the Settings page. Resetting invalidates all existing calendar subscriptions.
  • Events use RRULE:FREQ=YEARLY so birthdays repeat annually.
  • DTSTART uses only the month/day when birth_year_known is false.

Auth routes

These are handled by Auth.js v5 and are not documented here in detail. Key routes:

Route Method Purpose
/api/auth/[...nextauth] GET/POST Auth.js catch-all (session, CSRF)
/api/auth/register POST Create a new account (email + password)
/api/auth/forgot POST Send a password-reset email
/api/auth/reset POST Apply a new password using a reset token

Server actions

All mutations are Next.js server actions defined in app/people/actions.ts. They are called directly from client components using the "use server" directive — no HTTP fetch needed.

Key actions:

Action Purpose
createPerson Add a new person (handles photo upload)
updatePerson Edit person details (handles photo upload)
deletePerson Delete person and all related data
createWishlistItem Add a wishlist item to a person
updateWishlistItem Edit a wishlist item
deleteWishlistItem Remove a wishlist item
findProductsForWishlistItem Trigger AI + eBay product search
addManualProduct Save a manually-entered product
deleteProduct Remove a saved product
markItemGiven Set status to given and create a gift history entry
suggestGifts Call OpenRouter for AI gift suggestions
resetIcalToken Generate a new iCal token for the current user

Clone this wiki locally