POST /v1/bookmarks requires undocumented 'lastMutationAt' field

[sharabash]

Summary

The POST /v1/bookmarks endpoint returns 422 Unprocessable Entity with the message "lastMutationAt" is required, but this field is not documented in the Add user bookmark API docs.

Observed behavior

Request:

{
  "key": 2,
  "type": "ayah",
  "verseNumber": 255,
  "mushaf": 4
}

Response: 422 Unprocessable Entity

{
  "message": "\"lastMutationAt\" is required",
  "type": "unprocessable_entity",
  "success": false
}

Expected behavior

Either:

1. The lastMutationAt field should be documented (type, format, and purpose), or
2. The field should be optional with a server-side default if not provided

Context

The documented request body schema (add-user-bookmark.api.mdx) lists only key, type, verseNumber, isReading, and mushaf as fields. The lastMutationAt field is not mentioned anywhere in the docs.

Tested against: https://apis-prelive.quran.foundation/auth/v1/bookmarks

[osamasayed]

Salam @sharabash currently pre-live is having sync featured that is not on prod yet. Doc of it is here https://sync-apis.qf-api-docs.pages.dev

[sharabash]

Update: lastMutationAt affects ALL bookmark write endpoints

E2E testing confirms this isn't limited to POST /v1/bookmarks. The following endpoints all return 422: "lastMutationAt" is required:

Method	Endpoint	Operation
POST	/v1/bookmarks	Create bookmark
DELETE	/v1/bookmarks/:id	Delete bookmark

Both are blocked by this undocumented required field. The read endpoints (GET /v1/bookmarks, GET /v1/bookmarks/bookmark, GET /v1/bookmarks/ayahs-range) work fine.

Tested against: https://apis-prelive.quran.foundation/auth/v1/bookmarks

[sharabash]

Further update: lastMutationAt also affects ALL collection write endpoints

In addition to bookmarks (this issue) and notes (#74), collections are also blocked:

Method	Endpoint	Operation
POST	/auth/v1/collections	Create collection
POST	/auth/v1/collections/:id	Update collection
DELETE	/auth/v1/collections/:id	Delete collection
POST	/auth/v1/collections/:id/bookmarks	Add bookmark to collection

All return 422: "lastMutationAt" is required.

Summary of all affected endpoints across bookmarks, notes, and collections:

• POST /auth/v1/bookmarks (create)
• DELETE /auth/v1/bookmarks/:id (delete)
• POST /auth/v1/notes (create)
• PATCH /auth/v1/notes/:id (update)
• DELETE /auth/v1/notes/:id (delete)
• POST /auth/v1/notes/:id/publish (publish)
• POST /auth/v1/collections (create)
• POST /auth/v1/collections/:id (update)
• DELETE /auth/v1/collections/:id (delete)
• POST /auth/v1/collections/:id/bookmarks (add bookmark)

10 endpoints total, all blocked by the same undocumented required field.