Birthdays
Today's birthdays, sending wishes, and hearting or replying to the wishes you received.
Today's birthdays, sending wishes, and hearting or replying to the wishes you received.
Generated from the OpenAPI spec by
npm run docs:api -w api. Do not edit this page — change the decorators inapps/api/src/and regenerate.
Conventions
- Auth — a session on every route: the cookie on web, the bearer token on mobile. See Authentication.
- Errors — every non-2xx response has the body described in Errors.
- Types — a
?after a field name means it is optional;| nullmeans it is present but may be null.
Endpoints
GET /api/v1/birthdays/today — Who is celebrating a birthday today
Today in the company's timezone. Names and photos only — never a date of birth, so nobody learns anybody else’s age. The first call on somebody's birthday also sends everyone that day's birthday notification.
Returns 200 → BirthdayResponse[]
| Error | When |
|---|---|
401 | No valid session. Clear the stored token and sign in again. |
403 | Signed in, but not allowed to do this. |
GET /api/v1/birthdays/me/wishes — The birthday wishes you have received this year
Newest first. Only ever your own — nobody can read yours.
Returns 200 → BirthdayWishResponse[]
| Error | When |
|---|---|
401 | No valid session. Clear the stored token and sign in again. |
403 | Signed in, but not allowed to do this. |
POST /api/v1/birthdays/{userId}/wishes — Wish somebody a happy birthday
Only on their birthday, and not to yourself. One wish per person per birthday: sending again replaces the words, and only the first notifies.
| Path parameter | Type | Notes |
|---|---|---|
userId | string | Whose birthday it is. |
Body — SendWishDto
Returns 204 → no body
| Error | When |
|---|---|
400 | The request was rejected. message is an array of field errors when validation failed. |
401 | No valid session. Clear the stored token and sign in again. |
403 | Signed in, but not allowed to do this. |
404 | It is not their birthday today. |
PUT /api/v1/birthdays/wishes/{wishId}/love — Heart a wish you received, or take the heart back
Only the person the wish was sent to. The first heart notifies whoever wrote it.
| Path parameter | Type | Notes |
|---|---|---|
wishId | string |
Body — LoveWishDto
Returns 204 → no body
| Error | When |
|---|---|
400 | The request was rejected. message is an array of field errors when validation failed. |
401 | No valid session. Clear the stored token and sign in again. |
403 | Signed in, but not allowed to do this. |
404 | No such wish of yours. |
PUT /api/v1/birthdays/wishes/{wishId}/reply — Reply to a wish you received
Only the person the wish was sent to. One reply per wish — sending again rewords it, and an empty message clears it. The first reply notifies whoever wrote the wish, with its words.
| Path parameter | Type | Notes |
|---|---|---|
wishId | string |
Body — ReplyToWishDto
Returns 204 → no body
| Error | When |
|---|---|
400 | The request was rejected. message is an array of field errors when validation failed. |
401 | No valid session. Clear the stored token and sign in again. |
403 | Signed in, but not allowed to do this. |
404 | No such wish of yours. |
Data models
BirthdayResponse
| Field | Type | Notes |
|---|---|---|
id | string | |
name | string | |
image | string | null | |
title | string | |
wished | boolean | Whether you have already wished them this year. |
wishCount | number | Wishes received this year — only on your own entry, 0 on anybody else's. |
BirthdayWishResponse
| Field | Type | Notes |
|---|---|---|
id | string | |
author | MentionResponse | |
message | string | |
createdAt | string ISO 8601 | |
loved | boolean | Whether you have hearted it. |
reply | string | null | Your reply to it, or null. |
repliedAt | string ISO 8601 | null |
MentionResponse
| Field | Type | Notes |
|---|---|---|
id | string | |
name | string | |
image | string | null |
SendWishDto
| Field | Type | Notes |
|---|---|---|
message | string | The wish itself, as the person celebrating will read it. · ≤ 500 chars |
LoveWishDto
| Field | Type | Notes |
|---|---|---|
loved | boolean | true to heart the wish, false to take the heart back. |
ReplyToWishDto
| Field | Type | Notes |
|---|---|---|
message | string | The reply. Empty clears it. · ≤ 500 chars |