# info.description
API for Wish List, a small social network where people share gift ideas, events, stories, comments, reactions, notifications, and friendship actions.

# paths./api/admin/comments/{id}/.delete.description
Permanently delete a comment for moderation purposes.

# paths./api/admin/detected-abuse/.get.description
Return potential abusive content detected automatically.

# paths./api/admin/detected-abuse/.get.summary
List automatically detected abuse candidates

# paths./api/admin/items/{id}/.delete.description
Permanently delete a wish item for moderation purposes.

# paths./api/admin/reported/comments/.get.description
List all comments that users have reported for moderation.

# paths./api/admin/reported/comments/.get.parameters[].description
A page number within the paginated result set.

# paths./api/admin/reported/items/.get.description
List all wish items that have been reported by users.

# paths./api/admin/reported/items/.get.parameters[].description
A page number within the paginated result set.

# paths./api/admin/reported/stories/.get.description
List all stories that have been reported by users.

# paths./api/admin/reported/stories/.get.parameters[].description
A page number within the paginated result set.

# paths./api/admin/stories/{id}/.delete.description
Permanently delete a story for moderation purposes.

# paths./api/admin/users/.get.description
List and search user accounts for administrators.

Returns a paginated list of all user accounts.  Staff may filter
results using a ``search`` query parameter which performs a case‑
insensitive match on usernames, first names, last names and email
addresses.  Only staff (``is_staff=True``) may access this endpoint.

# paths./api/admin/users/.get.parameters[].description
A page number within the paginated result set.

# paths./api/admin/users/{username}/deactivate/.post.description
Deactivate a user account by setting the ``is_active`` flag to false.

To prevent accidental lock‑out of privileged users, accounts
marked with either ``is_superuser`` or ``is_staff`` are protected
and cannot be deactivated through this endpoint.  The test suite
expects that even staff members (``is_staff=True``) are
safeguarded.  A 400 response is returned when attempting to
deactivate a protected account; 404 is returned if the user does
not exist; and 200 is returned when a normal user is successfully
deactivated.

# paths./api/auth/csrf/.get.description
Issue a CSRF cookie and return its value.

Single-page applications need a CSRF token to call cookie-based
endpoints such as refresh and logout.  Browsers can obtain the
token by calling this endpoint.  The CSRF middleware will set
a ``csrftoken`` cookie on the response if one is not already present.
The token value is also returned in the response body for
convenience.

# paths./api/auth/login/.post.description
Authenticate a user and issue short-lived access and long-lived refresh tokens.

This endpoint validates the supplied credentials and, if the user's email
has been verified (``is_active=True``), returns an access token in the
response body and sets a refresh token as an HttpOnly cookie.  Unverified
users receive a 400 response with a descriptive error message.

# paths./api/auth/logout/.post.description
Invalidate the current refresh token and remove the cookie.

This endpoint revokes the refresh token stored in the ``refresh_token``
cookie, if present, and deletes the cookie on the client.  It returns
a simple confirmation message.  Like the refresh endpoint, CSRF
protection applies because it uses cookies.

# paths./api/auth/refresh/.post.description
Exchange a valid refresh token for a new access token and rotate the refresh token.

Clients should call this endpoint when the access token is expired or
about to expire.  The refresh token must be supplied in an HttpOnly
cookie named ``refresh_token``.  If the token is valid and not
revoked, the server issues a new access token and sets a new refresh
token cookie.  The old token is marked as revoked.  CSRF protection
applies because this endpoint uses cookies for authentication.

# paths./api/auth/register/.post.description
API endpoint that allows clients to register a new user account.

When a user is created, a verification token is generated and
a verification email is sent.

# paths./api/auth/resend-verification/.post.description
Validate the email, create a new token if needed,
and send a fresh verification email.

# paths./api/auth/reset-password/.post.description
Send a reset link when the email exists.

# paths./api/auth/reset-password/confirm/.post.description
Validate the token and update the user password.

# paths./api/auth/verify-email/{token}/.get.description
Activate the user associated with the token.

If the token is invalid or already used, return an error response.

# paths./api/auth/verify-email/status/.get.description
Return the verification status for a given email address.

# paths./api/cities/.get.description
List city master data filtered by a search query.

# paths./api/cities/.get.parameters[].description
A page number within the paginated result set.

# paths./api/countries/.get.description
List available countries with localized names.

# paths./api/interests/.get.description
List all active interests or filter them by search query.

This endpoint can be used by the front‑end to implement
autocomplete when users type their interests.  Only interests with
``is_active=True`` are returned.  A ``search`` query parameter
filters by slug, localized name, or category.

# paths./api/interests/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/blocks/.get.description
List profiles blocked by the current user.

# paths./api/me/blocks/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/comments/{comment_id}/reactions/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/comments/{comment_id}/reactions/{reaction_id}/.get.description
Retrieve, update or delete a reaction on a comment.

# paths./api/me/comments/{comment_id}/reactions/{reaction_id}/.put.description
Retrieve, update or delete a reaction on a comment.

# paths./api/me/comments/{comment_id}/reactions/{reaction_id}/.patch.description
Retrieve, update or delete a reaction on a comment.

# paths./api/me/comments/{comment_id}/reactions/{reaction_id}/.delete.description
Retrieve, update or delete a reaction on a comment.

# paths./api/me/comments/{comment_id}/report/.post.description
Endpoint to flag a comment as reported for abuse or spam.

Any authenticated user may report a comment.  The comment is marked
as reported and the endpoint returns a 200 response.  Subsequent
reports have no additional effect.  Reporting does not delete the
comment; moderation tooling would handle removal separately.

# paths./api/me/email/.post.description
Update the user's email and send a verification message.

# paths./api/me/events/.get.description
List and create events for the authenticated user.

* **GET** returns all events belonging to the current user ordered
  chronologically.
* **POST** creates a new event.  The profile of the current user
  is automatically attached.  Clients may specify a
  ``target_profile_id`` and ``wishlist`` association.

# paths./api/me/events/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/events/.post.description
List and create events for the authenticated user.

* **GET** returns all events belonging to the current user ordered
  chronologically.
* **POST** creates a new event.  The profile of the current user
  is automatically attached.  Clients may specify a
  ``target_profile_id`` and ``wishlist`` association.

# paths./api/me/events/{event_id}/comments/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/events/{event_id}/comments/{comment_id}/.get.description
Retrieve, update or delete a comment on an event.

# paths./api/me/events/{event_id}/comments/{comment_id}/.put.description
Retrieve, update or delete a comment on an event.

# paths./api/me/events/{event_id}/comments/{comment_id}/.patch.description
Retrieve, update or delete a comment on an event.

# paths./api/me/events/{event_id}/comments/{comment_id}/.delete.description
Retrieve, update or delete a comment on an event.

# paths./api/me/events/{event_id}/excluded-profiles/.get.description
List and create event-specific exclusions.

# paths./api/me/events/{event_id}/excluded-profiles/.post.description
List and create event-specific exclusions.

# paths./api/me/events/{event_id}/notify/.post.description
Send one event notification to one eligible friend.

# paths./api/me/events/{event_id}/organizers/{username}/.patch.description
Update or remove one organizer relation.

# paths./api/me/events/{event_id}/organizers/{username}/.delete.description
Update or remove one organizer relation.

# paths./api/me/events/{event_id}/reactions/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/events/{event_id}/reactions/{reaction_id}/.get.description
Retrieve, update or delete a reaction on an event.

# paths./api/me/events/{event_id}/reactions/{reaction_id}/.put.description
Retrieve, update or delete a reaction on an event.

# paths./api/me/events/{event_id}/reactions/{reaction_id}/.patch.description
Retrieve, update or delete a reaction on an event.

# paths./api/me/events/{event_id}/reactions/{reaction_id}/.delete.description
Retrieve, update or delete a reaction on an event.

# paths./api/me/events/{event_id}/wish-items/.get.description
List the current user's wish items associated with one event.

# paths./api/me/events/{event_id}/wish-items/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/events/{id}/.get.description
Retrieve, update or delete a single event.

Only the owner of the event may access it.  Attempting to access an
event not belonging to the current user results in a 404.

# paths./api/me/events/{id}/.put.description
Retrieve, update or delete a single event.

Only the owner of the event may access it.  Attempting to access an
event not belonging to the current user results in a 404.

# paths./api/me/events/{id}/.patch.description
Retrieve, update or delete a single event.

Only the owner of the event may access it.  Attempting to access an
event not belonging to the current user results in a 404.

# paths./api/me/events/{id}/.delete.description
Retrieve, update or delete a single event.

Only the owner of the event may access it.  Attempting to access an
event not belonging to the current user results in a 404.

# paths./api/me/feed/.get.description
Build, paginate and return canonical feed items.

# paths./api/me/feed/engagements/.post.description
Ingest feed engagement analytics for ranking signals.

# paths./api/me/feed/exposures/.post.description
Ingest feed item exposure analytics when an item appears.

# paths./api/me/friends/.get.description
List the current user's friends.

This view returns the authenticated user's friends using the
REST framework's list mixin.  Because the project uses a
pagination class globally, the response is automatically broken
into pages and includes metadata fields such as ``count``, ``next`` and
``previous``.  Clients can request a specific page via the ``page``
query parameter.  Authentication is required; unauthenticated
requests will return a 401 or 403 depending on the authentication
backend.

# paths./api/me/friends/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/friends/{username}/.post.description
Send a connection request or remove an existing connection.

* **POST** `/api/me/friends/<username>/` : Send a connection
  request to the user identified by ``<username>``.  If a
  connection or pending request already exists in either
  direction, a 400 error is returned.  The authenticated user
  cannot send a request to themselves.
* **DELETE** `/api/me/friends/<username>/` : Remove an
  existing connection with ``<username>`` or cancel a pending
  outgoing request.  If no such relation exists, a 404 is
  returned.

# paths./api/me/friends/{username}/.delete.description
Send a connection request or remove an existing connection.

* **POST** `/api/me/friends/<username>/` : Send a connection
  request to the user identified by ``<username>``.  If a
  connection or pending request already exists in either
  direction, a 400 error is returned.  The authenticated user
  cannot send a request to themselves.
* **DELETE** `/api/me/friends/<username>/` : Remove an
  existing connection with ``<username>`` or cancel a pending
  outgoing request.  If no such relation exists, a 404 is
  returned.

# paths./api/me/friends/{username}/.delete.summary
Remove a friend or cancel a pending request

# paths./api/me/friends/invite/.post.description
Validate the target email address and send an invitation.

# paths./api/me/friendship-requests/.get.description
List pending connection requests for the current user.

By default, this endpoint returns incoming pending requests (those
where the authenticated user is the recipient).  Clients may
specify ``?direction=outgoing`` to list requests that the user has
sent and that are still pending.  As a ``ListAPIView`` the
response is automatically paginated according to the global
pagination settings.  Authentication is required.

# paths./api/me/friendship-requests/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/friendship-requests/{id}/accept/.post.description
Accept a pending connection request.

Only the recipient of the request may accept it.  Upon acceptance
both profiles are added to each other's friends.  The request
status is updated to ``accepted``.  If the request does not exist
or is not pending, a 404 is returned.

# paths./api/me/friendship-requests/{id}/decline/.post.description
Decline a pending connection request.

Only the recipient of the request may decline it.  The request
status is updated to ``declined``.  A 204 response indicates
successful decline.  If the request is not found, a 404 is returned.

# paths./api/me/notification-preferences/.get.description
Retrieve or update notification preferences for the current user.

**GET** returns all possible notification type and channel combinations
merged with the user's saved preferences.  Missing preferences are
returned with ``enabled`` set to true (the default).  The response
structure is a list of objects with ``type``, ``channel`` and
``enabled`` fields under a top-level ``preferences`` key.

**PATCH** accepts a JSON body containing a ``preferences`` list of
objects.  Each object must have a ``type``, a ``channel`` and a
boolean ``enabled`` flag.  Unknown types or channels result in a
400 error.  Preferences that are not included in the request remain
unchanged.  The updated list of preferences is returned.

# paths./api/me/notification-preferences/.patch.description
Retrieve or update notification preferences for the current user.

**GET** returns all possible notification type and channel combinations
merged with the user's saved preferences.  Missing preferences are
returned with ``enabled`` set to true (the default).  The response
structure is a list of objects with ``type``, ``channel`` and
``enabled`` fields under a top-level ``preferences`` key.

**PATCH** accepts a JSON body containing a ``preferences`` list of
objects.  Each object must have a ``type``, a ``channel`` and a
boolean ``enabled`` flag.  Unknown types or channels result in a
400 error.  Preferences that are not included in the request remain
unchanged.  The updated list of preferences is returned.

# paths./api/me/notifications/.get.description
List notifications for the current user.

This endpoint returns a paginated list of notifications ordered by
creation time (newest first).  Pass ``is_read=true`` or
``is_read=false`` as query parameters to filter by read status.  When
omitted, all notifications are returned.

# paths./api/me/notifications/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/notifications/{id}/.get.description
Retrieve or update a single notification.

Currently only the ``is_read`` flag can be updated.  Attempts to
modify other fields are ignored.  A 404 is returned when the
notification does not belong to the authenticated user.  Partial
updates (PATCH) are supported.

# paths./api/me/notifications/{id}/.put.description
Retrieve or update a single notification.

Currently only the ``is_read`` flag can be updated.  Attempts to
modify other fields are ignored.  A 404 is returned when the
notification does not belong to the authenticated user.  Partial
updates (PATCH) are supported.

# paths./api/me/notifications/{id}/.patch.description
Retrieve or update a single notification.

Currently only the ``is_read`` flag can be updated.  Attempts to
modify other fields are ignored.  A 404 is returned when the
notification does not belong to the authenticated user.  Partial
updates (PATCH) are supported.

# paths./api/me/notifications/delete/.post.description
Delete multiple notifications for the current user.

# paths./api/me/notifications/mark-read/.post.description
Mark multiple notifications as read for the current user.

# paths./api/me/notifications/mark-unread/.post.description
Mark multiple notifications as unread for the current user.

# paths./api/me/notifications/seen/.post.description
Record the last time the current user opened notifications.

# paths./api/me/notifications/summary/.get.description
Return unread count and last seen timestamp for the current user.

# paths./api/me/onboarding/status/.get.description
Provide onboarding status for the authenticated user.

The response includes the last completed step, next step, and a
completion flag that the frontend can map to routes.

# paths./api/me/onboarding/steps/complete/.post.description
Mark an onboarding step as completed for the authenticated user.

The server stores the highest completed step, ignoring lower values.

# paths./api/me/password/.post.description
Validate the current password and set a new password.

# paths./api/me/profile/.get.description
Retrieve, create, update or delete the accounts of the currently authenticated user.

* **GET** returns the current user's accounts. If it does not exist, one is
  created automatically so that clients always receive a accounts object.
* **POST** explicitly creates an account if one does not already exist. If the
  account already exists, a 400 response is returned.  A POST can be
  useful after deleting an account to re‑create it.
* **PUT** fully replaces the existing accounts with the payload provided.  Fields
  omitted from the request are reset to their defaults.  This method
  supports nested relationships for children, sizes and interests and will
  replace existing nested objects.
* **PATCH** partially updates the accounts.  Only fields present in the
  request are modified.
* **DELETE** removes the accounts.  After deletion, a subsequent GET will
  automatically create a fresh accounts.  Clients that want to avoid
  implicit creation can detect the absence of a accounts via the 204
  response from DELETE and explicitly create a new accounts using POST.

JSON requests are supported alongside multipart form uploads for avatar
files by specifying appropriate parsers.  When sending JSON, the
``Content‑Type`` header should be ``application/json`` and nested
structures (children, sizes, interests) should be represented as JSON
objects or lists.  When uploading an avatar, use multipart form data.

# paths./api/me/profile/.post.description
Create a profile for the authenticated user.

If a profile already exists for the user, return a 400 response.
Otherwise create the profile with the provided data and return
the newly created representation.

# paths./api/me/profile/.put.description
Fully update the profile.  Fields not provided in the request are reset.

# paths./api/me/profile/.patch.description
Partially update the profile.  Only provided fields are modified.

# paths./api/me/push-subscriptions/.get.description
List and create push subscriptions for the current user.

**GET** returns all subscriptions associated with the authenticated user.

**POST** accepts a subscription object with ``endpoint``, a nested ``keys``
dictionary containing ``p256dh`` and ``auth`` strings, and an optional
``expiration_time``.  If a subscription for the same endpoint already
exists for the user, its keys and expiration time are updated.  The
response contains the persisted subscription.  A newly created
subscription returns status 201, while an update returns status 200.

# paths./api/me/push-subscriptions/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/push-subscriptions/.post.description
List and create push subscriptions for the current user.

**GET** returns all subscriptions associated with the authenticated user.

**POST** accepts a subscription object with ``endpoint``, a nested ``keys``
dictionary containing ``p256dh`` and ``auth`` strings, and an optional
``expiration_time``.  If a subscription for the same endpoint already
exists for the user, its keys and expiration time are updated.  The
response contains the persisted subscription.  A newly created
subscription returns status 201, while an update returns status 200.

# paths./api/me/push-subscriptions/{id}/.get.description
Retrieve or delete a single push subscription for the current user.

**GET** returns the details of the specified subscription.  A 404 is
returned if the subscription does not belong to the authenticated user.

**DELETE** removes the subscription and returns a 204 No Content
response.

# paths./api/me/push-subscriptions/{id}/.delete.description
Retrieve or delete a single push subscription for the current user.

**GET** returns the details of the specified subscription.  A 404 is
returned if the subscription does not belong to the authenticated user.

**DELETE** removes the subscription and returns a 204 No Content
response.

# paths./api/me/search/items/.get.description
Search within the authenticated user's own wish list items.

Returns a paginated list of items belonging to any of the current
user's wish lists that match the free text query.  Optional query
parameters ``min_price``, ``max_price`` and ``item_type`` further
filter the results.  Only authenticated users may use this
endpoint.

Example:

``GET /api/me/search/items/?q=laptop&min_price=100&item_type=buy``

# paths./api/me/search/items/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/stories/.get.description
List and create stories for the authenticated user.

* **GET** returns all stories authored by the current user.
* **POST** creates a new story.  Clients must supply either text
  content or an image, otherwise a validation error is returned.  The
  associated accounts is determined from the logged-in user.  The
  ``visibility`` field defaults to ``friends`` but can be overridden
  by the request payload.

# paths./api/me/stories/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/stories/.post.description
List and create stories for the authenticated user.

* **GET** returns all stories authored by the current user.
* **POST** creates a new story.  Clients must supply either text
  content or an image, otherwise a validation error is returned.  The
  associated accounts is determined from the logged-in user.  The
  ``visibility`` field defaults to ``friends`` but can be overridden
  by the request payload.

# paths./api/me/stories/{id}/.get.description
Retrieve, update or delete a specific story owned by the authenticated user.

The ``pk`` URL parameter identifies the story.  Only the author of the
story may view, modify or delete it.  Expired stories remain
accessible to the author until removed.

# paths./api/me/stories/{id}/.put.description
Retrieve, update or delete a specific story owned by the authenticated user.

The ``pk`` URL parameter identifies the story.  Only the author of the
story may view, modify or delete it.  Expired stories remain
accessible to the author until removed.

# paths./api/me/stories/{id}/.patch.description
Retrieve, update or delete a specific story owned by the authenticated user.

The ``pk`` URL parameter identifies the story.  Only the author of the
story may view, modify or delete it.  Expired stories remain
accessible to the author until removed.

# paths./api/me/stories/{id}/.delete.description
Retrieve, update or delete a specific story owned by the authenticated user.

The ``pk`` URL parameter identifies the story.  Only the author of the
story may view, modify or delete it.  Expired stories remain
accessible to the author until removed.

# paths./api/me/stories/{story_id}/comments/.get.description
List and create comments on a story owned by the current user.

# paths./api/me/stories/{story_id}/comments/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/stories/{story_id}/comments/.post.description
List and create comments on a story owned by the current user.

# paths./api/me/stories/{story_id}/comments/{comment_id}/.get.description
Retrieve, update or delete a comment on a story.

# paths./api/me/stories/{story_id}/comments/{comment_id}/.put.description
Retrieve, update or delete a comment on a story.

# paths./api/me/stories/{story_id}/comments/{comment_id}/.patch.description
Retrieve, update or delete a comment on a story.

# paths./api/me/stories/{story_id}/comments/{comment_id}/.delete.description
Retrieve, update or delete a comment on a story.

# paths./api/me/stories/{story_id}/reactions/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/stories/{story_id}/reactions/{reaction_id}/.get.description
Retrieve, update or delete a reaction on a story.

# paths./api/me/stories/{story_id}/reactions/{reaction_id}/.put.description
Retrieve, update or delete a reaction on a story.

# paths./api/me/stories/{story_id}/reactions/{reaction_id}/.patch.description
Retrieve, update or delete a reaction on a story.

# paths./api/me/stories/{story_id}/reactions/{reaction_id}/.delete.description
Retrieve, update or delete a reaction on a story.

# paths./api/me/stories/feed/.get.description
Return a feed of recent stories authored by the user and their friends.

Stories are ordered by creation's timestamp descending.  Only stories
that have not expired are included.  Stories authored by a
friends are returned only if their visibility is not set to
``only_me``.  The feed does not include public stories from
strangers in this initial implementation; it focuses on your
immediate network.

# paths./api/me/stories/feed/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/wishlists/.get.description
List and create wish lists for the authenticated user.

* **GET** returns all wish lists belonging to the current user.
  Lists are ordered by creation time, "newest first".
* **POST** creates a new wish list.  The profile of the current
  user is automatically attached.  The request body should
  include at least a ``name`` and can optionally include a
  description and visibility.

# paths./api/me/wishlists/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/wishlists/.post.description
List and create wish lists for the authenticated user.

* **GET** returns all wish lists belonging to the current user.
  Lists are ordered by creation time, "newest first".
* **POST** creates a new wish list.  The profile of the current
  user is automatically attached.  The request body should
  include at least a ``name`` and can optionally include a
  description and visibility.

# paths./api/me/wishlists/{id}/.get.description
Retrieve, update or delete a wish list owned by the authenticated user.

This endpoint only allows the owner of the wish list to view and
modify it.  Attempting to access another user's list will result
in a 404 response.  Nested wish items are returned in the
representation but must be managed via the item endpoints.

# paths./api/me/wishlists/{id}/.put.description
Retrieve, update or delete a wish list owned by the authenticated user.

This endpoint only allows the owner of the wish list to view and
modify it.  Attempting to access another user's list will result
in a 404 response.  Nested wish items are returned in the
representation but must be managed via the item endpoints.

# paths./api/me/wishlists/{id}/.patch.description
Retrieve, update or delete a wish list owned by the authenticated user.

This endpoint only allows the owner of the wish list to view and
modify it.  Attempting to access another user's list will result
in a 404 response.  Nested wish items are returned in the
representation but must be managed via the item endpoints.

# paths./api/me/wishlists/{id}/.delete.description
Retrieve, update or delete a wish list owned by the authenticated user.

This endpoint only allows the owner of the wish list to view and
modify it.  Attempting to access another user's list will result
in a 404 response.  Nested wish items are returned in the
representation but must be managed via the item endpoints.

# paths./api/me/wishlists/{wishlist_id}/comments/.get.description
List and create comments on a wish list owned by the current user.

* **GET** returns a paginated list of comments on the specified wish list.
* **POST** creates a new comment on the wish list.  The request must
  include a ``content`` field and may include ``parent`` to reply to
  another comment.  The authenticated user is automatically set as
  the author.  Only wish lists owned by the current user can be
  commented on via this endpoint.

# paths./api/me/wishlists/{wishlist_id}/comments/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/wishlists/{wishlist_id}/comments/.post.description
List and create comments on a wish list owned by the current user.

* **GET** returns a paginated list of comments on the specified wish list.
* **POST** creates a new comment on the wish list.  The request must
  include a ``content`` field and may include ``parent`` to reply to
  another comment.  The authenticated user is automatically set as
  the author.  Only wish lists owned by the current user can be
  commented on via this endpoint.

# paths./api/me/wishlists/{wishlist_id}/comments/{comment_id}/.get.description
Retrieve, update or delete a comment on a wish list owned by the user.

Only the author of a comment may update or delete it.  Attempts to
modify another user's comment result in a 403 response.  Retrieval
is allowed for any comment on the user's own wish list.  Comments
are looked up by the ``comment_id`` URL parameter.

# paths./api/me/wishlists/{wishlist_id}/comments/{comment_id}/.put.description
Retrieve, update or delete a comment on a wish list owned by the user.

Only the author of a comment may update or delete it.  Attempts to
modify another user's comment result in a 403 response.  Retrieval
is allowed for any comment on the user's own wish list.  Comments
are looked up by the ``comment_id`` URL parameter.

# paths./api/me/wishlists/{wishlist_id}/comments/{comment_id}/.patch.description
Retrieve, update or delete a comment on a wish list owned by the user.

Only the author of a comment may update or delete it.  Attempts to
modify another user's comment result in a 403 response.  Retrieval
is allowed for any comment on the user's own wish list.  Comments
are looked up by the ``comment_id`` URL parameter.

# paths./api/me/wishlists/{wishlist_id}/comments/{comment_id}/.delete.description
Retrieve, update or delete a comment on a wish list owned by the user.

Only the author of a comment may update or delete it.  Attempts to
modify another user's comment result in a 403 response.  Retrieval
is allowed for any comment on the user's own wish list.  Comments
are looked up by the ``comment_id`` URL parameter.

# paths./api/me/wishlists/{wishlist_id}/items/.get.description
List and create items within a specific wish list.

The URL must include the ID of the wish list in which the items
reside.  Only the owner of the list may create or view items in
that list.  The representation of an item includes all its
attributes.  Use the update and delete endpoints to modify or
remove items.

# paths./api/me/wishlists/{wishlist_id}/items/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/wishlists/{wishlist_id}/items/.post.description
List and create items within a specific wish list.

The URL must include the ID of the wish list in which the items
reside.  Only the owner of the list may create or view items in
that list.  The representation of an item includes all its
attributes.  Use the update and delete endpoints to modify or
remove items.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/.get.description
Retrieve, update or delete a specific item within a wish list.

Access is restricted to the owner of the parent wish list.  If an
item is not found or does not belong to the specified list, a
404 response is returned.  PATCH and PUT allow partial and full
updates respectively.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/.put.description
Retrieve, update or delete a specific item within a wish list.

Access is restricted to the owner of the parent wish list.  If an
item is not found or does not belong to the specified list, a
404 response is returned.  PATCH and PUT allow partial and full
updates respectively.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/.patch.description
Retrieve, update or delete a specific item within a wish list.

Access is restricted to the owner of the parent wish list.  If an
item is not found or does not belong to the specified list, a
404 response is returned.  PATCH and PUT allow partial and full
updates respectively.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/.delete.description
Retrieve, update or delete a specific item within a wish list.

Access is restricted to the owner of the parent wish list.  If an
item is not found or does not belong to the specified list, a
404 response is returned.  PATCH and PUT allow partial and full
updates respectively.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/comments/.get.description
List and create comments on a wish item owned by the current user.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/comments/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/comments/.post.description
List and create comments on a wish item owned by the current user.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/comments/{commen.get.description
Retrieve, update or delete a comment on a wish item.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/comments/{commen.put.description
Retrieve, update or delete a comment on a wish item.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/comments/{commen.patch.description
Retrieve, update or delete a comment on a wish item.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/comments/{commen.delete.description
Retrieve, update or delete a comment on a wish item.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/excluded-profile.get.description
List and create profile exclusions for one owned wish item.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/excluded-profile.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/excluded-profile.post.description
List and create profile exclusions for one owned wish item.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/excluded-profile.delete.description
Delete one profile exclusion from one owned wish item.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reactions/.get.description
List and create reactions on a wish item.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reactions/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reactions/.post.description
List and create reactions on a wish item.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reactions/{react.get.description
Retrieve, update or delete a reaction on a wish item.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reactions/{react.put.description
Retrieve, update or delete a reaction on a wish item.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reactions/{react.patch.description
Retrieve, update or delete a reaction on a wish item.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reactions/{react.delete.description
Retrieve, update or delete a reaction on a wish item.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reservations/.get.description
List and create reservations on a wish item.

**GET** returns reservations on the specified item, subject to access
control.  Only the wish list owner and their friends may view
reservations.  The owner sees anonymous reservations (no profile
information) to avoid spoiling surprises.  Private reservations are
also anonymized for everyone except the reserver.

**POST** creates or updates a reservation for the current user.  The
request body may include ``status`` (``reserved`` or ``interested``)
and ``is_private`` (boolean).  Only friends of the list owner may
reserve an item; the owner cannot reserve their own items.  If a
reservation already exists for the user and item, it is updated
instead of creating a duplicate.  A 201 response indicates creation;
200 indicates an update.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reservations/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reservations/.post.description
List and create reservations on a wish item.

**GET** returns reservations on the specified item, subject to access
control.  Only the wish list owner and their friends may view
reservations.  The owner sees anonymous reservations (no profile
information) to avoid spoiling surprises.  Private reservations are
also anonymized for everyone except the reserver.

**POST** creates or updates a reservation for the current user.  The
request body may include ``status`` (``reserved`` or ``interested``)
and ``is_private`` (boolean).  Only friends of the list owner may
reserve an item; the owner cannot reserve their own items.  If a
reservation already exists for the user and item, it is updated
instead of creating a duplicate.  A 201 response indicates creation;
200 indicates an update.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reservations/{re.get.description
Retrieve, update or delete a reservation on a wish item.

**GET** returns the reservation details if the requester has access
(owner or connection).  The reserving user's identity may be hidden
depending on privacy settings and ownership as described above.

**PATCH/PUT** allows the reserver to update the status or privacy flag.
Only the reserver may modify their reservation.  Attempting to update
another user's reservation returns a 403.

**DELETE** allows the reserver to cancel their reservation.  Only the
reserver may delete the reservation; other users receive a 403.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reservations/{re.put.description
Retrieve, update or delete a reservation on a wish item.

**GET** returns the reservation details if the requester has access
(owner or connection).  The reserving user's identity may be hidden
depending on privacy settings and ownership as described above.

**PATCH/PUT** allows the reserver to update the status or privacy flag.
Only the reserver may modify their reservation.  Attempting to update
another user's reservation returns a 403.

**DELETE** allows the reserver to cancel their reservation.  Only the
reserver may delete the reservation; other users receive a 403.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reservations/{re.patch.description
Retrieve, update or delete a reservation on a wish item.

**GET** returns the reservation details if the requester has access
(owner or connection).  The reserving user's identity may be hidden
depending on privacy settings and ownership as described above.

**PATCH/PUT** allows the reserver to update the status or privacy flag.
Only the reserver may modify their reservation.  Attempting to update
another user's reservation returns a 403.

**DELETE** allows the reserver to cancel their reservation.  Only the
reserver may delete the reservation; other users receive a 403.

# paths./api/me/wishlists/{wishlist_id}/items/{item_id}/reservations/{re.delete.description
Retrieve, update or delete a reservation on a wish item.

**GET** returns the reservation details if the requester has access
(owner or connection).  The reserving user's identity may be hidden
depending on privacy settings and ownership as described above.

**PATCH/PUT** allows the reserver to update the status or privacy flag.
Only the reserver may modify their reservation.  Attempting to update
another user's reservation returns a 403.

**DELETE** allows the reserver to cancel their reservation.  Only the
reserver may delete the reservation; other users receive a 403.

# paths./api/me/wishlists/{wishlist_id}/reactions/.get.description
List and create reactions on a wish list.

Unlike the ``me``-scoped endpoints for items and lists, this view
permits authenticated users to react to a wish list they do not own
provided they are allowed to view the list.  Public lists are
visible to everyone; lists restricted to friends are visible
only to the owner and their friends; ``only_me`` lists are
visible only to the owner.  When a reaction is submitted by
someone other than the list owner, a notification is emitted to
the owner.  Clients may update an existing reaction by posting
again with a different ``reaction_type``; only one reaction per
user per list is stored.

# paths./api/me/wishlists/{wishlist_id}/reactions/.get.parameters[].description
A page number within the paginated result set.

# paths./api/me/wishlists/{wishlist_id}/reactions/.post.description
List and create reactions on a wish list.

Unlike the ``me``-scoped endpoints for items and lists, this view
permits authenticated users to react to a wish list they do not own
provided they are allowed to view the list.  Public lists are
visible to everyone; lists restricted to friends are visible
only to the owner and their friends; ``only_me`` lists are
visible only to the owner.  When a reaction is submitted by
someone other than the list owner, a notification is emitted to
the owner.  Clients may update an existing reaction by posting
again with a different ``reaction_type``; only one reaction per
user per list is stored.

# paths./api/me/wishlists/{wishlist_id}/reactions/{reaction_id}/.get.description
Retrieve, update or delete a reaction on a wish list.

This detail view looks up the parent list without restricting to the
current user and then filters the reaction by the requesting user
to enforce that only the reaction author may modify or delete
it.  Retrieval is allowed only for the author; attempts by other
users result in a 404 response.

# paths./api/me/wishlists/{wishlist_id}/reactions/{reaction_id}/.put.description
Retrieve, update or delete a reaction on a wish list.

This detail view looks up the parent list without restricting to the
current user and then filters the reaction by the requesting user
to enforce that only the reaction author may modify or delete
it.  Retrieval is allowed only for the author; attempts by other
users result in a 404 response.

# paths./api/me/wishlists/{wishlist_id}/reactions/{reaction_id}/.patch.description
Retrieve, update or delete a reaction on a wish list.

This detail view looks up the parent list without restricting to the
current user and then filters the reaction by the requesting user
to enforce that only the reaction author may modify or delete
it.  Retrieval is allowed only for the author; attempts by other
users result in a 404 response.

# paths./api/me/wishlists/{wishlist_id}/reactions/{reaction_id}/.delete.description
Retrieve, update or delete a reaction on a wish list.

This detail view looks up the parent list without restricting to the
current user and then filters the reaction by the requesting user
to enforce that only the reaction author may modify or delete
it.  Retrieval is allowed only for the author; attempts by other
users result in a 404 response.

# paths./api/media/images/.post.description
Create a new image upload for the authenticated user.

# paths./api/metrics/.get.description
Handle GET requests and return a JSON object with metrics.

# paths./api/search/.get.description
Perform a global search across people, wish lists, items, stories, and events.

Clients must supply a ``q`` query parameter containing the search
term.  The ``types`` parameter accepts a comma separated list of
result types to include: ``person``, ``wishlist``, ``item``, ``story``,
and ``event``.
When omitted, all types are included.  Filters applicable to
specific result types may also be provided:

  * ``people_country`` — restrict people search to a given country code
  * ``country`` — alias for ``people_country``
  * ``min_price`` and ``max_price`` — restrict item search by price
  * ``item_type`` — restrict item search to either ``buy`` or ``craft``
  * ``item_status`` — restrict item search by wish status
  * ``reservation_status`` — restrict item search by reservation state
  * ``people_age_min`` and ``people_age_max`` — restrict people by age range
  * ``people_gender`` — restrict people by gender
  * ``people_city`` — restrict people by city
  * ``people_relationship_status`` — restrict people by relationship status
  * ``people_joined_from`` and ``people_joined_to`` — restrict people by join date range
  * ``wishlist_created_from`` and ``wishlist_created_to`` — restrict wish lists by creation date
  * ``item_created_from`` and ``item_created_to`` — restrict wish items by creation date
  * ``story_created_from`` and ``story_created_to`` — restrict stories by creation date
  * ``event_created_from`` and ``event_created_to`` — restrict events by creation date
  * ``event_date_from`` and ``event_date_to`` — restrict events by event date

The response is paginated according to the global API settings and
returns a list of objects, each containing a ``type`` key and a
``data`` key.  The ``data`` key holds the serialized representation
appropriate for the type (e.g. user accounts, wish list, or item).
Only authenticated users may perform a global search.

# paths./api/search/.get.summary
Search globally across people and content

# paths./api/search/users/.get.description
Search for users by name.

This endpoint returns a paginated list of user profiles whose
username, first name, last name or display name match the query
string.  Only authenticated users may perform a search.  An
optional ``country`` query parameter narrows the results to a
specific country code.  The optional ``city`` query parameter
expects a city identifier from the city master data.  Results are
ordered alphabetically by username.

Example:

``GET /api/search/users/?q=ali&country=BE``

# paths./api/search/users/.get.parameters[].description
A page number within the paginated result set.

# paths./api/support/bug-report/.post.description
Receive bug reports and forward them to the support mailbox.

# paths./api/u/{username}/wishlists/.get.description
List wish lists for a given user with visibility enforcement.

# paths./api/u/{username}/wishlists/.get.parameters[].description
A page number within the paginated result set.

# paths./api/u/{username}/wishlists/{wishlist_id}/.get.description
Retrieve a single wish list for a given user with visibility enforcement.

# paths./api/u/{username}/wishlists/{wishlist_id}/items/.get.description
List one public user's visible wish list items with pagination and search.

# paths./api/u/{username}/wishlists/{wishlist_id}/items/.get.parameters[].description
A page number within the paginated result set.

# paths./api/u/{username}/wishlists/{wishlist_id}/items/{item_id}/.get.description
Retrieve one public wish list item when the parent list is visible.

# paths./api/users/{username}/events/.get.description
List events for a given user with visibility enforcement.

# paths./api/users/{username}/events/.get.parameters[].description
A page number within the paginated result set.

# paths./api/users/{username}/events/{event_id}/.get.description
Retrieve a single event for a given user with visibility enforcement.

# paths./api/users/{username}/events/{event_id}/attendance/.get.description
List event attendance and toggle the current viewer presence.

# paths./api/users/{username}/events/{event_id}/attendance/.put.description
List event attendance and toggle the current viewer presence.

# paths./api/users/{username}/events/{event_id}/attendance/.delete.description
List event attendance and toggle the current viewer presence.

# paths./api/users/{username}/events/{event_id}/wish-items/.get.description
List the visible wish items associated with one public event.

# paths./api/users/{username}/events/{event_id}/wish-items/.get.parameters[].description
A page number within the paginated result set.

# paths./api/users/{username}/events/{event_id}/wish-items/{item_id}/res.post.description
Reserve one associated event wish item for the authenticated visitor.

# paths./api/users/{username}/profile/.get.description
Return a user profile with visibility rules enforced.

# paths./api/users/{username}/search/items/.get.description
Search within another user's wish list items visible to the caller.

This endpoint returns items from the target user's wish lists that
the current user is permitted to view (public lists or lists
marked ``friends`` when there is a friendship between the
users).  It accepts the same free text and price/type filters as
``MyItemSearchView``.  A 404 response is returned if the target
user does not exist or has no visible lists.

Example:

``GET /api/users/alice/search/items/?q=book``

# paths./api/users/{username}/search/items/.get.parameters[].description
A page number within the paginated result set.

# paths./api/users/{username}/stories/.get.description
List stories for a given user with visibility enforcement.

# paths./api/users/{username}/stories/.get.parameters[].description
A page number within the paginated result set.

# paths./api/users/{username}/stories/{story_id}/.get.description
Retrieve a single story for a given user with visibility enforcement.

# paths./o/register/.post.description
Create a DOT application from validated dynamic client metadata.

# components.schemas.AbuseDetectionResponse.description
Schema for automatically detected abuse identifiers.

# components.schemas.AdminComment.description
Serializer for comments in the admin API including the reported flag.

Extends the base ``CommentSerializer`` to surface the ``reported`` field
used for moderation.  All fields remain read‑only in the admin context
because comments cannot be edited through the administration API.

# components.schemas.AdminComment.properties.reported.description
Flag indicating whether this comment has been reported for abuse or spam.

# components.schemas.AdminStory.description
Serializer for reporting stories in the admin API.

Returns the story identifier, author, content preview, the ``reported``
flag and timestamps.  The author accounts is represented using
``SimpleProfileSerializer`` for consistency with other endpoints.

# components.schemas.AdminStory.properties.content.description
Optional textual content of the story.  Either text or image must be provided.

# components.schemas.AdminStory.properties.reported.description
Flag indicating whether this story has been reported for abuse or spam. Stories marked as reported will be surfaced in the administration interface for review.

# components.schemas.AdminStory.properties.expires_at.description
Timestamp when the story will no longer appear in feeds.

# components.schemas.AdminUser.description
Serializer for listing and inspecting user accounts in the admin API.

This serializer exposes the most relevant fields on the built‑in
``User`` model for administrative tasks: username, email, first and
last names, active flag and join date.  It intentionally omits
sensitive information such as passwords and permission groups.  The
``id`` field is included to uniquely identify records in lists.

# components.schemas.AdminUser.properties.username.description
Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.

# components.schemas.AdminUser.properties.is_active.description
Designates whether this user should be treated as active. Unselect this instead of deleting accounts.

# components.schemas.AdminWishListItem.description
Serializer for reporting wish items in the admin API.

Exposes minimal information about a wish item required for moderation,
including its title, description, reported flag and timestamps.  The
associated wish list is represented by its identifier only.  All
fields are read only.

# components.schemas.AdminWishListItem.properties.title.description
Title of the wish item (e.g. 'Noise‑cancelling headphones').

# components.schemas.AdminWishListItem.properties.reported.description
Flag indicating whether this item has been reported for abuse or spam. Items marked as reported will be surfaced in the administration interface for review.

# components.schemas.AttendanceCreateResponse.description
Schema for attendance creation responses.

# components.schemas.AttendanceListResponse.description
Schema for paginated attendance responses with attendance metadata.

# components.schemas.BirthdateVisibilityEnum.description
* `full` - Full date
* `partial` - Day and month only
* `hidden` - Hidden

# components.schemas.BugReportRequest.description
Validate data submitted by users for bug reports.

# components.schemas.BulkIdsRequestRequest.description
Schema for optional bulk identifier lists.

# components.schemas.CategoryEnum.description
* `clothing` - Clothing
* `shoe` - Shoe
* `underwear` - Underwear
* `gloves` - Gloves
* `glasses` - Glasses
* `other` - Other

# components.schemas.ChangeEmailRequest.description
Serializer used to initiate an email change for an authenticated user.

# components.schemas.ChangeEmailRequest.properties.new_email.description
New email address to associate with the account.

# components.schemas.ChangeEmailRequest.properties.current_password.description
Current password used to confirm the change.

# components.schemas.ChangePasswordRequest.description
Serializer used to change the password for an authenticated user.

# components.schemas.ChangePasswordRequest.properties.old_password.description
Current password used to confirm the change.

# components.schemas.Child.description
Serializer for a child entry on a accounts.

# components.schemas.Child.properties.name.description
First name of the child.  Can be blank if the parent wants to keep it private.

# components.schemas.Child.properties.birthdate.description
Birthdate of the child.  Used for birthday reminders.

# components.schemas.ChildRequest.description
Serializer for a child entry on a accounts.

# components.schemas.ChildRequest.properties.name.description
First name of the child.  Can be blank if the parent wants to keep it private.

# components.schemas.ChildRequest.properties.birthdate.description
Birthdate of the child.  Used for birthday reminders.

# components.schemas.City.description
Serialize city master data for search selection.

# components.schemas.City.properties.country_name.description
Return the localized country name for the city.

# components.schemas.Comment.description
Serializer for comments on wish lists, items, stories or other comments.

When serialising (reading), the ``accounts`` field uses
``SimpleProfileSerializer`` to expose the author without sensitive
information.  When deserialising (writing), the authenticated user
is attached automatically in the view via ``serializer.save(accounts=...)``.
Clients may supply a ``parent`` to create a reply to an existing comment.

# components.schemas.CommentRequest.description
Serializer for comments on wish lists, items, stories or other comments.

When serialising (reading), the ``accounts`` field uses
``SimpleProfileSerializer`` to expose the author without sensitive
information.  When deserialising (writing), the authenticated user
is attached automatically in the view via ``serializer.save(accounts=...)``.
Clients may supply a ``parent`` to create a reply to an existing comment.

# components.schemas.ConnectionRequest.description
Serializer for connection requests.

Represents an invitation to connect from one accounts to another.  It
exposes both the sender and the recipient via the
``SimpleProfileSerializer``.  The primary key and status fields
allow clients to identify and act upon individual requests.

# components.schemas.ConnectionRequest.properties.status.description
Current state of the friendship request.

* `pending` - Pending
* `accepted` - Accepted
* `declined` - Declined

# components.schemas.ConnectionRequest.properties.created_at.description
Timestamp when the friendship request was created.

# components.schemas.ConnectionStatusEnum.description
* `pending` - Pending
* `accepted` - Accepted
* `declined` - Declined

# components.schemas.Country.description
Serialize country master data with localized names.

# components.schemas.Country.properties.name.description
Return a localized name from annotated data or translations.

# components.schemas.CsrfTokenResponse.description
Schema for the CSRF token endpoint response.

# components.schemas.DetailResponse.description
Schema for common responses that only contain a detail message.

# components.schemas.DistanceEnum.description
* `family` - Family
* `friend` - Friend
* `friend_of_friend` - Friend of friend
* `public` - Public
* `official` - Official

# components.schemas.EmailVerificationStatusResponse.description
Schema for email verification status responses.

# components.schemas.Event.description
Serializer for Event instances used in CRUD endpoints.

The serializer includes the owning profile and target profile as
nested simple profile representations when reading.  Clients may
optionally specify ``target_profile_id`` to associate the event
with another profile.  When linking a wish list, ``wishlist_id``
may be provided.  Read‑only fields include the owner profile and
timestamps.

# components.schemas.Event.properties.name.description
Name of the event (e.g. 'Birthday Party').

# components.schemas.Event.properties.description.description
Optional description providing more context about the event.

# components.schemas.Event.properties.time.description
Optional time of day for the event (HH:MM:SS).

# components.schemas.Event.properties.visibility.description
Who can see this event.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.Event.properties.viewer_permissions.description
Return the effective permissions for the current requester.

# components.schemas.Event.properties.attendance_summary.description
Return visible attendees and hidden attendee counts for the requester.

# components.schemas.Event.properties.vip.description
Feed priority override. Negative excludes from feed, zero is normal, positive is pinned above the standard feed.

# components.schemas.EventProfileMutationRequest.description
Validate a username payload for organizer and exclusion management.

# components.schemas.EventReference.description
Minimal serializer for referenced events.

# components.schemas.EventReference.properties.name.description
Name of the event (e.g. 'Birthday Party').

# components.schemas.EventReference.properties.description.description
Optional description providing more context about the event.

# components.schemas.EventReference.properties.time.description
Optional time of day for the event (HH:MM:SS).

# components.schemas.EventRequest.description
Serializer for Event instances used in CRUD endpoints.

The serializer includes the owning profile and target profile as
nested simple profile representations when reading.  Clients may
optionally specify ``target_profile_id`` to associate the event
with another profile.  When linking a wish list, ``wishlist_id``
may be provided.  Read‑only fields include the owner profile and
timestamps.

# components.schemas.EventRequest.properties.name.description
Name of the event (e.g. 'Birthday Party').

# components.schemas.EventRequest.properties.description.description
Optional description providing more context about the event.

# components.schemas.EventRequest.properties.time.description
Optional time of day for the event (HH:MM:SS).

# components.schemas.EventRequest.properties.visibility.description
Who can see this event.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.EventRequest.properties.target_profile_id.description
ID of the profile the event is about.  When omitted or null, the event relates to the owner.

# components.schemas.EventRequest.properties.vip.description
Feed priority override. Negative excludes from feed, zero is normal, positive is pinned above the standard feed.

# components.schemas.EventReservationResponse.description
Schema for quick event wish item reservation responses.

# components.schemas.FeedEngagementCreate.description
Serializer for feed engagement analytics ingestion.

# components.schemas.FeedEngagementCreate.properties.item_type.description
Canonical feed item type.

* `story` - Story
* `event` - Event
* `wish_item` - Wish item
* `official_item` - Official item
* `friendship_event` - Friendship event
* `friend_suggestion` - Friend suggestion

# components.schemas.FeedEngagementCreate.properties.source_kind.description
Underlying source model category.

* `story` - Story
* `event` - Event
* `wish_item` - Wish item
* `friendship_event` - Friendship event
* `feed_suggestion` - Feed suggestion

# components.schemas.FeedEngagementCreate.properties.time_spent_seconds.description
Time spent on the item during this interaction.

# components.schemas.FeedEngagementCreate.properties.text_progress_ratio.description
Reading progress ratio between zero and one.

# components.schemas.FeedEngagementCreate.properties.search_impressions.description
Number of search result impressions recorded.

# components.schemas.FeedEngagementCreate.properties.search_clicks.description
Number of search result clicks recorded.

# components.schemas.FeedEngagementCreate.properties.interactions_count.description
Number of explicit interactions such as comments or reactions.

# components.schemas.FeedEngagementCreate.properties.shares_count.description
Number of shares recorded for this engagement row.

# components.schemas.FeedEngagementCreate.properties.replay_count.description
Number of replay events recorded for this row.

# components.schemas.FeedEngagementCreate.properties.appeared_in_long_session.description
Whether this interaction happened during a long session.

# components.schemas.FeedEngagementCreate.properties.added_to_favorites.description
Whether the viewer added this item to favorites.

# components.schemas.FeedEngagementCreate.properties.commented.description
Whether the viewer commented this item during the interaction.

# components.schemas.FeedEngagementCreate.properties.reacted.description
Whether the viewer reacted to this item during the interaction.

# components.schemas.FeedEngagementCreateRequest.description
Serializer for feed engagement analytics ingestion.

# components.schemas.FeedEngagementCreateRequest.properties.item_type.description
Canonical feed item type.

* `story` - Story
* `event` - Event
* `wish_item` - Wish item
* `official_item` - Official item
* `friendship_event` - Friendship event
* `friend_suggestion` - Friend suggestion

# components.schemas.FeedEngagementCreateRequest.properties.source_kind.description
Underlying source model category.

* `story` - Story
* `event` - Event
* `wish_item` - Wish item
* `friendship_event` - Friendship event
* `feed_suggestion` - Feed suggestion

# components.schemas.FeedEngagementCreateRequest.properties.time_spent_seconds.description
Time spent on the item during this interaction.

# components.schemas.FeedEngagementCreateRequest.properties.text_progress_ratio.description
Reading progress ratio between zero and one.

# components.schemas.FeedEngagementCreateRequest.properties.search_impressions.description
Number of search result impressions recorded.

# components.schemas.FeedEngagementCreateRequest.properties.search_clicks.description
Number of search result clicks recorded.

# components.schemas.FeedEngagementCreateRequest.properties.interactions_count.description
Number of explicit interactions such as comments or reactions.

# components.schemas.FeedEngagementCreateRequest.properties.shares_count.description
Number of shares recorded for this engagement row.

# components.schemas.FeedEngagementCreateRequest.properties.replay_count.description
Number of replay events recorded for this row.

# components.schemas.FeedEngagementCreateRequest.properties.appeared_in_long_session.description
Whether this interaction happened during a long session.

# components.schemas.FeedEngagementCreateRequest.properties.added_to_favorites.description
Whether the viewer added this item to favorites.

# components.schemas.FeedEngagementCreateRequest.properties.commented.description
Whether the viewer commented this item during the interaction.

# components.schemas.FeedEngagementCreateRequest.properties.reacted.description
Whether the viewer reacted to this item during the interaction.

# components.schemas.FeedItem.description
Canonical serializer for items returned by the feed endpoint.

# components.schemas.FeedItemExposureCreate.description
Serializer for feed exposure analytics ingestion.

# components.schemas.FeedItemExposureCreate.properties.item_type.description
Canonical feed item type.

* `story` - Story
* `event` - Event
* `wish_item` - Wish item
* `official_item` - Official item
* `friendship_event` - Friendship event
* `friend_suggestion` - Friend suggestion

# components.schemas.FeedItemExposureCreate.properties.source_kind.description
Underlying source model category.

* `story` - Story
* `event` - Event
* `wish_item` - Wish item
* `friendship_event` - Friendship event
* `feed_suggestion` - Feed suggestion

# components.schemas.FeedItemExposureCreate.properties.appeared_at.description
Timestamp when the item was shown in the feed.

# components.schemas.FeedItemExposureCreateRequest.description
Serializer for feed exposure analytics ingestion.

# components.schemas.FeedItemExposureCreateRequest.properties.item_type.description
Canonical feed item type.

* `story` - Story
* `event` - Event
* `wish_item` - Wish item
* `official_item` - Official item
* `friendship_event` - Friendship event
* `friend_suggestion` - Friend suggestion

# components.schemas.FeedItemExposureCreateRequest.properties.source_kind.description
Underlying source model category.

* `story` - Story
* `event` - Event
* `wish_item` - Wish item
* `friendship_event` - Friendship event
* `feed_suggestion` - Feed suggestion

# components.schemas.FeedItemTypeEnum.description
* `story` - Story
* `event` - Event
* `wish_item` - Wish item
* `official_item` - Official item
* `friendship_event` - Friendship event
* `friend_suggestion` - Friend suggestion

# components.schemas.FriendProfile.description
Profile data for friend listings and friend filters.

# components.schemas.FriendProfile.properties.display_name.description
Nickname displayed in the app instead of first/last name.

# components.schemas.FriendProfile.properties.bio.description
Short biography or personal description.

# components.schemas.FriendProfile.properties.gender.description
Optional gender label selected by the user.

* `female` - Female
* `male` - Male
* `non_binary` - Non binary
* `other` - Other
* `prefer_not_to_say` - Prefer not to say

# components.schemas.FriendProfile.properties.country_name.description
Return the localized country name for list views.

# components.schemas.FriendReference.description
Minimal serializer for referenced friends.

# components.schemas.FriendReference.properties.display_name.description
Nickname displayed in the app instead of first/last name.

# components.schemas.GenderEnum.description
* `female` - Female
* `male` - Male
* `non_binary` - Non binary
* `other` - Other
* `prefer_not_to_say` - Prefer not to say

# components.schemas.GlobalSearchResponse.description
Schema for paginated global search responses.

# components.schemas.GlobalSearchResult.description
Schema for one typed global search result.

# components.schemas.GrantTypesEnum.description
* `authorization_code` - authorization_code
* `client_credentials` - client_credentials
* `password` - password
* `implicit` - implicit

# components.schemas.ImageUpload.description
Serializer for creating and returning image uploads.

# components.schemas.ImageUpload.properties.image.description
Uploaded image file that can be attached later.

# components.schemas.ImageUpload.properties.usage.description
Context in which the upload will be used.

* `profile_avatar` - Profile avatar
* `wish_item` - Wish item
* `event` - Event
* `story` - Story

# components.schemas.ImageUploadRequest.description
Serializer for creating and returning image uploads.

# components.schemas.ImageUploadRequest.properties.image.description
Uploaded image file that can be attached later.

# components.schemas.ImageUploadRequest.properties.usage.description
Context in which the upload will be used.

* `profile_avatar` - Profile avatar
* `wish_item` - Wish item
* `event` - Event
* `story` - Story

# components.schemas.Interest.description
Serializer for the global Interest model.

Only includes the slug and name.  Creation is allowed so that
users can supply a new interest by specifying a name; the slug
will be generated automatically.  If the interest already exists
(matching slug), it will be reused.

# components.schemas.Interest.properties.slug.description
Unique identifier used internally and for URLs.

# components.schemas.Interest.properties.category.description
Optional category such as 'sport', 'music', 'art', etc.

# components.schemas.InterestRequest.description
Serializer for the global Interest model.

Only includes the slug and name.  Creation is allowed so that
users can supply a new interest by specifying a name; the slug
will be generated automatically.  If the interest already exists
(matching slug), it will be reused.

# components.schemas.InterestRequest.properties.category.description
Optional category such as 'sport', 'music', 'art', etc.

# components.schemas.InviteByEmailRequest.description
Validate payloads used to invite someone by email.

# components.schemas.InviteByEmailRequest.properties.email.description
Email address that should receive the invitation.

# components.schemas.LoginRequest.description
Serializer used to authenticate a user with email and password.

It makes sure that:
  * credentials are valid
  * the user account is active (email verified)

# components.schemas.MediaTypeEnum.description
* `image` - Image
* `video` - Video
* `audio` - Audio

# components.schemas.MetricsResponse.description
Schema for administrative metrics responses.

# components.schemas.Notification.description
Serialize notifications for listing in the notification center.

# components.schemas.Notification.properties.payload.description
Optional structured data describing the notification context.

# components.schemas.Notification.properties.target.description
Return the navigation target for the notification.

# components.schemas.Notification.properties.is_read.description
Flag indicating whether the notification has been read.

# components.schemas.Notification.properties.read_at.description
Timestamp when the notification was marked as read.

# components.schemas.NotificationPreferenceEntry.description
Schema for one notification preference entry.

# components.schemas.NotificationPreferenceEntryRequest.description
Schema for one notification preference entry.

# components.schemas.NotificationPreferenceList.description
Schema for notification preference list responses and updates.

# components.schemas.NotificationRequest.description
Serialize notifications for listing in the notification center.

# components.schemas.NotificationRequest.properties.is_read.description
Flag indicating whether the notification has been read.

# components.schemas.NotificationSeenResponse.description
Schema for notification seen timestamp responses.

# components.schemas.NotificationSummaryResponse.description
Schema for notification summary responses.

# components.schemas.OAuthClientRegistrationRequestRequest.description
Schema for dynamic OAuth2 client registration requests.

# components.schemas.OAuthClientRegistrationResponse.description
Schema for dynamic OAuth2 client registration responses.

# components.schemas.OAuthErrorResponse.description
Schema for OAuth2 dynamic registration errors.

# components.schemas.OnboardingStatus.description
Serializer for onboarding status responses.

# components.schemas.OnboardingStepCompleteRequest.description
Serializer for onboarding step completion requests.

# components.schemas.OnboardingStepCompleteRequest.properties.step_id.description
The onboarding step number that is now completed.

# components.schemas.OrganizerProfileResponse.description
Schema for organizer profile responses with event permissions.

# components.schemas.PatchedCommentRequest.description
Serializer for comments on wish lists, items, stories or other comments.

When serialising (reading), the ``accounts`` field uses
``SimpleProfileSerializer`` to expose the author without sensitive
information.  When deserialising (writing), the authenticated user
is attached automatically in the view via ``serializer.save(accounts=...)``.
Clients may supply a ``parent`` to create a reply to an existing comment.

# components.schemas.PatchedEventRequest.description
Serializer for Event instances used in CRUD endpoints.

The serializer includes the owning profile and target profile as
nested simple profile representations when reading.  Clients may
optionally specify ``target_profile_id`` to associate the event
with another profile.  When linking a wish list, ``wishlist_id``
may be provided.  Read‑only fields include the owner profile and
timestamps.

# components.schemas.PatchedEventRequest.properties.name.description
Name of the event (e.g. 'Birthday Party').

# components.schemas.PatchedEventRequest.properties.description.description
Optional description providing more context about the event.

# components.schemas.PatchedEventRequest.properties.time.description
Optional time of day for the event (HH:MM:SS).

# components.schemas.PatchedEventRequest.properties.visibility.description
Who can see this event.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PatchedEventRequest.properties.target_profile_id.description
ID of the profile the event is about.  When omitted or null, the event relates to the owner.

# components.schemas.PatchedEventRequest.properties.vip.description
Feed priority override. Negative excludes from feed, zero is normal, positive is pinned above the standard feed.

# components.schemas.PatchedNotificationPreferenceListRequest.description
Schema for notification preference list responses and updates.

# components.schemas.PatchedNotificationRequest.description
Serialize notifications for listing in the notification center.

# components.schemas.PatchedNotificationRequest.properties.is_read.description
Flag indicating whether the notification has been read.

# components.schemas.PatchedProfileRequest.description
Serializer for the Profile model and related data.

This serializer exposes both the built‑in ``User`` fields (first_name,
last_name and email) and the extended accounts fields.  Nested
representations are used for children, sizes and interests.  On
update, nested objects are replaced if provided.  Partial updates
are supported via PATCH (fields not present in the request
remain unchanged).

# components.schemas.PatchedProfileRequest.properties.display_name.description
Nickname displayed in the app instead of first/last name.

# components.schemas.PatchedProfileRequest.properties.bio.description
Short biography or personal description.

# components.schemas.PatchedProfileRequest.properties.birthdate_visibility.description
How the birth date should be visible to others.

* `full` - Full date
* `partial` - Day and month only
* `hidden` - Hidden

# components.schemas.PatchedProfileRequest.properties.gender.description
Optional gender label selected by the user.

* `female` - Female
* `male` - Male
* `non_binary` - Non binary
* `other` - Other
* `prefer_not_to_say` - Prefer not to say

# components.schemas.PatchedProfileRequest.properties.language.description
Preferred interface language (e.g. en, fr).

# components.schemas.PatchedProfileRequest.properties.relationship_status.description
Relationship status selection.

* `single` - Single
* `in_relationship` - In a relationship
* `married` - Married
* `civil_union` - Civil union
* `separated` - Separated
* `divorced` - Divorced
* `widowed` - Widowed
* `prefer_not_to_say` - Prefer not to say

# components.schemas.PatchedProfileRequest.properties.relationship_start_date.description
Start date of the relationship, used for reminders such as anniversaries.

# components.schemas.PatchedProfileRequest.properties.global_visibility.description
Who can discover and view this profile globally.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PatchedProfileRequest.properties.name_visibility.description
Who can see the user's first and last name.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PatchedProfileRequest.properties.birthdate_section_visibility.description
Who can see the user's birthdate section.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PatchedProfileRequest.properties.sizes_visibility.description
Who can see the user's sizes information.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PatchedProfileRequest.properties.relationship_visibility.description
Who can see the user's relationship status and dates.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PatchedProfileRequest.properties.feed_include_events.description
Whether event items are included in the personalized feed.

# components.schemas.PatchedProfileRequest.properties.feed_include_wishes.description
Whether wish item updates are included in the personalized feed.

# components.schemas.PatchedProfileRequest.properties.feed_include_official_items.description
Whether official account items are included in the personalized feed.

# components.schemas.PatchedProfileRequest.properties.feed_include_friendship_events.description
Whether friendship activity events are included in the personalized feed.

# components.schemas.PatchedProfileRequest.properties.feed_include_friend_suggestions.description
Whether friend suggestions are included in the personalized feed.

# components.schemas.PatchedReactionRequest.description
Serializer for reactions on wish lists, items, stories or comments.

When reading, the ``accounts`` field uses ``SimpleProfileSerializer`` to
expose the reacting user.  When writing, the view must supply the
target object and the author accounts; clients only need to set
``reaction_type``.  Validation ensures that the provided reaction type
is among the allowed values defined on the model.

# components.schemas.PatchedReactionRequest.properties.reaction_type.description
Type of reaction (heart, like or idea).

* `heart` - Heart
* `like` - Like
* `idea` - Idea

# components.schemas.PatchedReservationRequest.description
Serializer for reservations on wish items.

When reading, the ``accounts`` field uses ``SimpleProfileSerializer`` to
expose the reserving user.  When writing, clients may set the
``status`` and ``is_private`` fields; the view will attach the
``accounts`` and ``wish_list_item``.  Validation ensures that the provided
status is one of the allowed choices defined on the model.

# components.schemas.PatchedReservationRequest.properties.status.description
Indicates whether the reserver is offering or interested in the item.

* `reserved` - Reserved
* `interested` - Interested

# components.schemas.PatchedReservationRequest.properties.is_private.description
Whether this reservation is hidden from other friends.

# components.schemas.PatchedStoryRequest.description
Serializer for the ``Story`` model.

Ensures that either ``content`` or ``image`` is supplied when creating
a new story.  The ``accounts`` is represented by the
``SimpleProfileSerializer`` for read operations and is read‑only.  The
``created_at`` and ``expires_at`` fields are also read‑only to
prevent clients from forging timestamps.

# components.schemas.PatchedStoryRequest.properties.visibility.description
Controls who can see this story.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PatchedStoryRequest.properties.vip.description
Feed priority override. Negative excludes from feed, zero is normal, positive is pinned above the standard feed.

# components.schemas.PatchedWishListDetailRequest.description
Serializer for a single wish list without nested items.

The authenticated owner's detail page now loads wish items from the
dedicated paginated item endpoint. Excluding nested items here keeps
the detail payload compact even when a list contains many wishes.

# components.schemas.PatchedWishListDetailRequest.properties.name.description
Name of the wish list (e.g. 'Birthday 2025').

# components.schemas.PatchedWishListDetailRequest.properties.description.description
Optional description providing more context about the list.

# components.schemas.PatchedWishListDetailRequest.properties.visibility.description
Who can see this wish list.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PatchedWishListItemRequest.description
Serializer for WishListItem instances.

This serializer exposes all fields defined on the WishListItem model.  The
``id`` field is read‑only.  The ``image`` field is represented using
its URL when available.  Price fields accept decimal numbers or null.

# components.schemas.PatchedWishListItemRequest.properties.title.description
Title of the wish item (e.g. 'Noise‑cancelling headphones').

# components.schemas.PatchedWishListItemRequest.properties.category.description
Optional category of the item (e.g. 'tech', 'book', etc.).

# components.schemas.PatchedWishListItemRequest.properties.item_type.description
Indicates whether the item should be purchased or crafted.

* `buy` - Buy
* `craft` - Craft

# components.schemas.PatchedWishListItemRequest.properties.priority.description
Importance of the item, influences sorting order.

* `low` - Low
* `medium` - Medium
* `high` - High

# components.schemas.PatchedWishListItemRequest.properties.status.description
Current status of the item (wished, received, or no longer needed).

* `still_wished` - Still wished
* `received` - Received
* `no_longer_wished` - No longer wished

# components.schemas.PatchedWishListItemRequest.properties.visibility.description
Who can see this item.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PatchedWishListItemRequest.properties.vip.description
Feed priority override. Negative excludes from feed, zero is normal, positive is pinned above the standard feed.

# components.schemas.PriorityEnum.description
* `low` - Low
* `medium` - Medium
* `high` - High

# components.schemas.Profile.description
Serializer for the Profile model and related data.

This serializer exposes both the built‑in ``User`` fields (first_name,
last_name and email) and the extended accounts fields.  Nested
representations are used for children, sizes and interests.  On
update, nested objects are replaced if provided.  Partial updates
are supported via PATCH (fields not present in the request
remain unchanged).

# components.schemas.Profile.properties.display_name.description
Nickname displayed in the app instead of first/last name.

# components.schemas.Profile.properties.bio.description
Short biography or personal description.

# components.schemas.Profile.properties.birthdate_visibility.description
How the birth date should be visible to others.

* `full` - Full date
* `partial` - Day and month only
* `hidden` - Hidden

# components.schemas.Profile.properties.country_name.description
Return the localized country name for profile responses.

# components.schemas.Profile.properties.gender.description
Optional gender label selected by the user.

* `female` - Female
* `male` - Male
* `non_binary` - Non binary
* `other` - Other
* `prefer_not_to_say` - Prefer not to say

# components.schemas.Profile.properties.language.description
Preferred interface language (e.g. en, fr).

# components.schemas.Profile.properties.relationship_status.description
Relationship status selection.

* `single` - Single
* `in_relationship` - In a relationship
* `married` - Married
* `civil_union` - Civil union
* `separated` - Separated
* `divorced` - Divorced
* `widowed` - Widowed
* `prefer_not_to_say` - Prefer not to say

# components.schemas.Profile.properties.relationship_start_date.description
Start date of the relationship, used for reminders such as anniversaries.

# components.schemas.Profile.properties.global_visibility.description
Who can discover and view this profile globally.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.Profile.properties.name_visibility.description
Who can see the user's first and last name.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.Profile.properties.birthdate_section_visibility.description
Who can see the user's birthdate section.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.Profile.properties.sizes_visibility.description
Who can see the user's sizes information.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.Profile.properties.relationship_visibility.description
Who can see the user's relationship status and dates.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.Profile.properties.feed_include_events.description
Whether event items are included in the personalized feed.

# components.schemas.Profile.properties.feed_include_wishes.description
Whether wish item updates are included in the personalized feed.

# components.schemas.Profile.properties.feed_include_official_items.description
Whether official account items are included in the personalized feed.

# components.schemas.Profile.properties.feed_include_friendship_events.description
Whether friendship activity events are included in the personalized feed.

# components.schemas.Profile.properties.feed_include_friend_suggestions.description
Whether friend suggestions are included in the personalized feed.

# components.schemas.Profile.properties.can_manage_feed_priority.description
Return whether the profile user may assign positive feed priority.

# components.schemas.ProfileRequest.description
Serializer for the Profile model and related data.

This serializer exposes both the built‑in ``User`` fields (first_name,
last_name and email) and the extended accounts fields.  Nested
representations are used for children, sizes and interests.  On
update, nested objects are replaced if provided.  Partial updates
are supported via PATCH (fields not present in the request
remain unchanged).

# components.schemas.ProfileRequest.properties.display_name.description
Nickname displayed in the app instead of first/last name.

# components.schemas.ProfileRequest.properties.bio.description
Short biography or personal description.

# components.schemas.ProfileRequest.properties.birthdate_visibility.description
How the birth date should be visible to others.

* `full` - Full date
* `partial` - Day and month only
* `hidden` - Hidden

# components.schemas.ProfileRequest.properties.gender.description
Optional gender label selected by the user.

* `female` - Female
* `male` - Male
* `non_binary` - Non binary
* `other` - Other
* `prefer_not_to_say` - Prefer not to say

# components.schemas.ProfileRequest.properties.language.description
Preferred interface language (e.g. en, fr).

# components.schemas.ProfileRequest.properties.relationship_status.description
Relationship status selection.

* `single` - Single
* `in_relationship` - In a relationship
* `married` - Married
* `civil_union` - Civil union
* `separated` - Separated
* `divorced` - Divorced
* `widowed` - Widowed
* `prefer_not_to_say` - Prefer not to say

# components.schemas.ProfileRequest.properties.relationship_start_date.description
Start date of the relationship, used for reminders such as anniversaries.

# components.schemas.ProfileRequest.properties.global_visibility.description
Who can discover and view this profile globally.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.ProfileRequest.properties.name_visibility.description
Who can see the user's first and last name.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.ProfileRequest.properties.birthdate_section_visibility.description
Who can see the user's birthdate section.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.ProfileRequest.properties.sizes_visibility.description
Who can see the user's sizes information.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.ProfileRequest.properties.relationship_visibility.description
Who can see the user's relationship status and dates.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.ProfileRequest.properties.feed_include_events.description
Whether event items are included in the personalized feed.

# components.schemas.ProfileRequest.properties.feed_include_wishes.description
Whether wish item updates are included in the personalized feed.

# components.schemas.ProfileRequest.properties.feed_include_official_items.description
Whether official account items are included in the personalized feed.

# components.schemas.ProfileRequest.properties.feed_include_friendship_events.description
Whether friendship activity events are included in the personalized feed.

# components.schemas.ProfileRequest.properties.feed_include_friend_suggestions.description
Whether friend suggestions are included in the personalized feed.

# components.schemas.ProfileSize.description
Serializer for a size entry on a accounts.

# components.schemas.ProfileSize.properties.category.description
Type of size (clothing, shoe, etc.).

* `clothing` - Clothing
* `shoe` - Shoe
* `underwear` - Underwear
* `gloves` - Gloves
* `glasses` - Glasses
* `other` - Other

# components.schemas.ProfileSize.properties.title.description
Human readable description of the size, for instance 'EU Shirt'.

# components.schemas.ProfileSize.properties.unit.description
Unit or sizing system (e.g. 'EU', 'US').

# components.schemas.ProfileSizeRequest.description
Serializer for a size entry on a accounts.

# components.schemas.ProfileSizeRequest.properties.category.description
Type of size (clothing, shoe, etc.).

* `clothing` - Clothing
* `shoe` - Shoe
* `underwear` - Underwear
* `gloves` - Gloves
* `glasses` - Glasses
* `other` - Other

# components.schemas.ProfileSizeRequest.properties.title.description
Human readable description of the size, for instance 'EU Shirt'.

# components.schemas.ProfileSizeRequest.properties.unit.description
Unit or sizing system (e.g. 'EU', 'US').

# components.schemas.PublicProfile.description
Serializer for viewing another user's profile with visibility checks.

# components.schemas.PublicProfile.properties.display_name.description
Nickname displayed in the app instead of first/last name.

# components.schemas.PublicProfile.properties.bio.description
Short biography or personal description.

# components.schemas.PublicProfile.properties.birthdate_visibility.description
How the birth date should be visible to others.

* `full` - Full date
* `partial` - Day and month only
* `hidden` - Hidden

# components.schemas.PublicProfile.properties.country_name.description
Return the localized country name for public profiles.

# components.schemas.PublicProfile.properties.gender.description
Optional gender label selected by the user.

* `female` - Female
* `male` - Male
* `non_binary` - Non binary
* `other` - Other
* `prefer_not_to_say` - Prefer not to say

# components.schemas.PublicProfile.properties.relationship_status.description
Relationship status selection.

* `single` - Single
* `in_relationship` - In a relationship
* `married` - Married
* `civil_union` - Civil union
* `separated` - Separated
* `divorced` - Divorced
* `widowed` - Widowed
* `prefer_not_to_say` - Prefer not to say

# components.schemas.PublicProfile.properties.relationship_start_date.description
Start date of the relationship, used for reminders such as anniversaries.

# components.schemas.PublicProfile.properties.sizes_visibility.description
Who can see the user's sizes information.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PublicProfile.properties.relationship_visibility.description
Who can see the user's relationship status and dates.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PublicProfile.properties.name_visibility.description
Who can see the user's first and last name.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PublicProfile.properties.birthdate_section_visibility.description
Who can see the user's birthdate section.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PublicProfile.properties.global_visibility.description
Who can discover and view this profile globally.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.PushSubscription.description
Serializer for push notification subscriptions.

The ``keys`` field is a dictionary containing ``p256dh`` and ``auth``
strings as returned by the browser's subscription object.  An optional
``expiration_time`` may be supplied when the browser includes it.

# components.schemas.PushSubscription.properties.endpoint.description
The push service endpoint URL for this subscription.

# components.schemas.PushSubscriptionRequest.description
Serializer for push notification subscriptions.

The ``keys`` field is a dictionary containing ``p256dh`` and ``auth``
strings as returned by the browser's subscription object.  An optional
``expiration_time`` may be supplied when the browser includes it.

# components.schemas.PushSubscriptionRequest.properties.endpoint.description
The push service endpoint URL for this subscription.

# components.schemas.Reaction.description
Serializer for reactions on wish lists, items, stories or comments.

When reading, the ``accounts`` field uses ``SimpleProfileSerializer`` to
expose the reacting user.  When writing, the view must supply the
target object and the author accounts; clients only need to set
``reaction_type``.  Validation ensures that the provided reaction type
is among the allowed values defined on the model.

# components.schemas.Reaction.properties.reaction_type.description
Type of reaction (heart, like or idea).

* `heart` - Heart
* `like` - Like
* `idea` - Idea

# components.schemas.ReactionRequest.description
Serializer for reactions on wish lists, items, stories or comments.

When reading, the ``accounts`` field uses ``SimpleProfileSerializer`` to
expose the reacting user.  When writing, the view must supply the
target object and the author accounts; clients only need to set
``reaction_type``.  Validation ensures that the provided reaction type
is among the allowed values defined on the model.

# components.schemas.ReactionRequest.properties.reaction_type.description
Type of reaction (heart, like or idea).

* `heart` - Heart
* `like` - Like
* `idea` - Idea

# components.schemas.ReactionTypeEnum.description
* `heart` - Heart
* `like` - Like
* `idea` - Idea

# components.schemas.Register.description
Serializer used to register a new user account.

It requires a password confirmation and ensures that:
  * passwords match
  * username and email are unique

# components.schemas.RegisterRequest.description
Serializer used to register a new user account.

It requires a password confirmation and ensures that:
  * passwords match
  * username and email are unique

# components.schemas.RegisterRequest.properties.password_confirm.description
Password confirmation, must be identical to password.

# components.schemas.RelationshipStatusEnum.description
* `single` - Single
* `in_relationship` - In a relationship
* `married` - Married
* `civil_union` - Civil union
* `separated` - Separated
* `divorced` - Divorced
* `widowed` - Widowed
* `prefer_not_to_say` - Prefer not to say

# components.schemas.ResendVerificationRequest.description
Serializer used to request a new verification email.

It validates that:
  * a user with the given email exists
  * the user is not already active

# components.schemas.ResendVerificationRequest.properties.email.description
Email address of the account that must receive a new verification email.

# components.schemas.Reservation.description
Serializer for reservations on wish items.

When reading, the ``accounts`` field uses ``SimpleProfileSerializer`` to
expose the reserving user.  When writing, clients may set the
``status`` and ``is_private`` fields; the view will attach the
``accounts`` and ``wish_list_item``.  Validation ensures that the provided
status is one of the allowed choices defined on the model.

# components.schemas.Reservation.properties.status.description
Indicates whether the reserver is offering or interested in the item.

* `reserved` - Reserved
* `interested` - Interested

# components.schemas.Reservation.properties.is_private.description
Whether this reservation is hidden from other friends.

# components.schemas.ReservationRequest.description
Serializer for reservations on wish items.

When reading, the ``accounts`` field uses ``SimpleProfileSerializer`` to
expose the reserving user.  When writing, clients may set the
``status`` and ``is_private`` fields; the view will attach the
``accounts`` and ``wish_list_item``.  Validation ensures that the provided
status is one of the allowed choices defined on the model.

# components.schemas.ReservationRequest.properties.status.description
Indicates whether the reserver is offering or interested in the item.

* `reserved` - Reserved
* `interested` - Interested

# components.schemas.ReservationRequest.properties.is_private.description
Whether this reservation is hidden from other friends.

# components.schemas.ReservationStatusEnum.description
* `reserved` - Reserved
* `interested` - Interested

# components.schemas.ResetPasswordConfirmRequest.description
Serializer used to validate a password reset submission.

# components.schemas.ResetPasswordConfirmRequest.properties.token.description
Combined token containing the user identifier and reset token.

# components.schemas.ResetPasswordConfirmRequest.properties.password_confirm.description
Password confirmation, must be identical to password.

# components.schemas.ResetPasswordRequestRequest.description
Serializer used to request a password reset email.

# components.schemas.ResetPasswordRequestRequest.properties.email.description
Email address that should receive the reset link.

# components.schemas.SeverityEnum.description
* `low` - low
* `medium` - medium
* `high` - high
* `blocker` - blocker

# components.schemas.SimpleProfile.description
Minimal representation of a user profile for listing friends.

Includes the user's username, first and last name and the display
name set on the profile.  Email addresses and other private
attributes are deliberately excluded.

# components.schemas.SimpleProfile.properties.display_name.description
Nickname displayed in the app instead of first/last name.

# components.schemas.SimpleProfileRequest.description
Minimal representation of a user profile for listing friends.

Includes the user's username, first and last name and the display
name set on the profile.  Email addresses and other private
attributes are deliberately excluded.

# components.schemas.SimpleProfileRequest.properties.display_name.description
Nickname displayed in the app instead of first/last name.

# components.schemas.SourceKindEnum.description
* `story` - Story
* `event` - Event
* `wish_item` - Wish item
* `friendship_event` - Friendship event
* `feed_suggestion` - Feed suggestion

# components.schemas.StatusResponse.description
Schema for common responses that only contain a status value.

# components.schemas.Story.description
Serializer for the ``Story`` model.

Ensures that either ``content`` or ``image`` is supplied when creating
a new story.  The ``accounts`` is represented by the
``SimpleProfileSerializer`` for read operations and is read‑only.  The
``created_at`` and ``expires_at`` fields are also read‑only to
prevent clients from forging timestamps.

# components.schemas.Story.properties.visibility.description
Controls who can see this story.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.Story.properties.vip.description
Feed priority override. Negative excludes from feed, zero is normal, positive is pinned above the standard feed.

# components.schemas.Story.properties.expires_at.description
Timestamp when the story will no longer appear in feeds.

# components.schemas.StoryReference.description
Minimal serializer for referenced stories in related assets.

# components.schemas.StoryReference.properties.content.description
Optional textual content of the story.  Either text or image must be provided.

# components.schemas.StoryReference.properties.image.description
Optional image attached to the story.  Either content or media must be provided.

# components.schemas.StoryReference.properties.media_type.description
Type of media associated with the story.

* `image` - Image
* `video` - Video
* `audio` - Audio

# components.schemas.StoryReference.properties.media_url.description
Optional media link for video or audio stories.

# components.schemas.StoryRequest.description
Serializer for the ``Story`` model.

Ensures that either ``content`` or ``image`` is supplied when creating
a new story.  The ``accounts`` is represented by the
``SimpleProfileSerializer`` for read operations and is read‑only.  The
``created_at`` and ``expires_at`` fields are also read‑only to
prevent clients from forging timestamps.

# components.schemas.StoryRequest.properties.visibility.description
Controls who can see this story.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.StoryRequest.properties.vip.description
Feed priority override. Negative excludes from feed, zero is normal, positive is pinned above the standard feed.

# components.schemas.TokenEndpointAuthMethodEnum.description
* `client_secret_basic` - client_secret_basic
* `client_secret_post` - client_secret_post
* `none` - none

# components.schemas.TokenResponse.description
Schema for login and refresh token responses.

# components.schemas.TypeEnum.description
* `person` - person
* `wishlist` - wishlist
* `item` - item
* `story` - story
* `event` - event

# components.schemas.UsageEnum.description
* `profile_avatar` - Profile avatar
* `wish_item` - Wish item
* `event` - Event
* `story` - Story

# components.schemas.UserInterest.description
Serializer linking a user profile to a specific interest with extra info.

# components.schemas.UserInterest.properties.importance.description
How important this interest is for the user.

* `1` - Low
* `2` - Medium
* `3` - High

# components.schemas.UserInterest.properties.visibility.description
Who can see that the user has this interest.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.UserInterestRequest.description
Serializer linking a user profile to a specific interest with extra info.

# components.schemas.UserInterestRequest.properties.importance.description
How important this interest is for the user.

* `1` - Low
* `2` - Medium
* `3` - High

# components.schemas.UserInterestRequest.properties.visibility.description
Who can see that the user has this interest.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.UsernameMutationRequestRequest.description
Schema for requests that only contain a username.

# components.schemas.VisibilityEnum.description
* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.WishItemReference.description
Minimal serializer for referenced wish list items.

# components.schemas.WishItemReference.properties.title.description
Title of the wish item (e.g. 'Noise‑cancelling headphones').

# components.schemas.WishList.description
Serializer for WishList instances.

Provides serialization and deserialization for wish lists.  The
``items`` field returns a nested list of items when reading, but
nested creation of items is not supported on the wish list
serializer.  Use the dedicated item endpoints to add items to a
list.  The ``slug`` field is read‑only and automatically
generated on creation.

# components.schemas.WishList.properties.name.description
Name of the wish list (e.g. 'Birthday 2025').

# components.schemas.WishList.properties.description.description
Optional description providing more context about the list.

# components.schemas.WishList.properties.visibility.description
Who can see this wish list.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.WishList.properties.items.description
Serialize only the nested items visible to the current requester.

# components.schemas.WishListDetail.description
Serializer for a single wish list without nested items.

The authenticated owner's detail page now loads wish items from the
dedicated paginated item endpoint. Excluding nested items here keeps
the detail payload compact even when a list contains many wishes.

# components.schemas.WishListDetail.properties.name.description
Name of the wish list (e.g. 'Birthday 2025').

# components.schemas.WishListDetail.properties.description.description
Optional description providing more context about the list.

# components.schemas.WishListDetail.properties.visibility.description
Who can see this wish list.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.WishListDetailRequest.description
Serializer for a single wish list without nested items.

The authenticated owner's detail page now loads wish items from the
dedicated paginated item endpoint. Excluding nested items here keeps
the detail payload compact even when a list contains many wishes.

# components.schemas.WishListDetailRequest.properties.name.description
Name of the wish list (e.g. 'Birthday 2025').

# components.schemas.WishListDetailRequest.properties.description.description
Optional description providing more context about the list.

# components.schemas.WishListDetailRequest.properties.visibility.description
Who can see this wish list.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.WishListItem.description
Serializer for WishListItem instances.

This serializer exposes all fields defined on the WishListItem model.  The
``id`` field is read‑only.  The ``image`` field is represented using
its URL when available.  Price fields accept decimal numbers or null.

# components.schemas.WishListItem.properties.title.description
Title of the wish item (e.g. 'Noise‑cancelling headphones').

# components.schemas.WishListItem.properties.category.description
Optional category of the item (e.g. 'tech', 'book', etc.).

# components.schemas.WishListItem.properties.item_type.description
Indicates whether the item should be purchased or crafted.

* `buy` - Buy
* `craft` - Craft

# components.schemas.WishListItem.properties.priority.description
Importance of the item, influences sorting order.

* `low` - Low
* `medium` - Medium
* `high` - High

# components.schemas.WishListItem.properties.status.description
Current status of the item (wished, received, or no longer needed).

* `still_wished` - Still wished
* `received` - Received
* `no_longer_wished` - No longer wished

# components.schemas.WishListItem.properties.visibility.description
Who can see this item.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.WishListItem.properties.vip.description
Feed priority override. Negative excludes from feed, zero is normal, positive is pinned above the standard feed.

# components.schemas.WishListItem.properties.current_viewer_reservation.description
Return the current viewer reservation summary when it exists.

# components.schemas.WishListItem.properties.reserved_by_others.description
Return True when another person already reserved the item.

# components.schemas.WishListItem.properties.associated_events.description
Return events linked to the item and visible to the current viewer.

# components.schemas.WishListItemRequest.description
Serializer for WishListItem instances.

This serializer exposes all fields defined on the WishListItem model.  The
``id`` field is read‑only.  The ``image`` field is represented using
its URL when available.  Price fields accept decimal numbers or null.

# components.schemas.WishListItemRequest.properties.title.description
Title of the wish item (e.g. 'Noise‑cancelling headphones').

# components.schemas.WishListItemRequest.properties.category.description
Optional category of the item (e.g. 'tech', 'book', etc.).

# components.schemas.WishListItemRequest.properties.item_type.description
Indicates whether the item should be purchased or crafted.

* `buy` - Buy
* `craft` - Craft

# components.schemas.WishListItemRequest.properties.priority.description
Importance of the item, influences sorting order.

* `low` - Low
* `medium` - Medium
* `high` - High

# components.schemas.WishListItemRequest.properties.status.description
Current status of the item (wished, received, or no longer needed).

* `still_wished` - Still wished
* `received` - Received
* `no_longer_wished` - No longer wished

# components.schemas.WishListItemRequest.properties.visibility.description
Who can see this item.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# components.schemas.WishListItemRequest.properties.vip.description
Feed priority override. Negative excludes from feed, zero is normal, positive is pinned above the standard feed.

# components.schemas.WishListItemStatusEnum.description
* `still_wished` - Still wished
* `received` - Received
* `no_longer_wished` - No longer wished

# components.schemas.WishListRequest.description
Serializer for WishList instances.

Provides serialization and deserialization for wish lists.  The
``items`` field returns a nested list of items when reading, but
nested creation of items is not supported on the wish list
serializer.  Use the dedicated item endpoints to add items to a
list.  The ``slug`` field is read‑only and automatically
generated on creation.

# components.schemas.WishListRequest.properties.name.description
Name of the wish list (e.g. 'Birthday 2025').

# components.schemas.WishListRequest.properties.description.description
Optional description providing more context about the list.

# components.schemas.WishListRequest.properties.visibility.description
Who can see this wish list.

* `only_me` - Only me
* `friends` - Friends
* `friends_of_friends` - Friends of friends
* `everyone` - Everyone

# tags[].description
Account registration, login, logout, password reset, and email verification.

# tags[].description
OAuth2 authorization, token, and dynamic client registration endpoints.

# tags[].description
Current user profile, public profiles, onboarding, and user search.

# tags[].description
Wish lists, items, comments, reactions, exclusions, reservations, and item search.

# tags[].description
Events, attendance, event wish items, organizers, comments, reactions, and visibility exclusions.

# tags[].description
Stories, story feed, related assets, comments, reactions, and moderation.

# tags[].description
Friends, invitations, blocked profiles, and friendship requests.

# tags[].description
Personalized feed items and feed analytics ingestion.

# tags[].description
Global search and focused user or item search.

# tags[].description
Administrative moderation endpoints for reported content and abuse signals.