0 Fork 0

Files

T

John O'Keefe 6f13dc2b63 docs(media-items core): Beam WO5 batch 4 — 12 endpoints backfilled, registry pinned

Beam backfilled list/get/create/update/delete media-item, search, ratings
CRUD, progress GET/PUT. Beam correctly identified create/update/delete as
jwt+admin (admin group in the router — verified).

Claude registry: 12 entries. Notable pins:
- get_media_item: hand-built ~44-key map pinned verbatim from the handler
- create/update return the full database.MediaItems row (74 columns) —
  examples merged up to the real shape via gate-driven merge script
- search returns []SearchMediaItemsRow (sqlc row — Real type pinned)
- rating scale is 1-10 int (odd = half-star); GET returns {rating: null} when
  absent; update reuses the create handler (201)
- progress GET: 25 base keys + 4 CONDITIONAL position-authority keys
  (css_selector/anchor_href/char_offset/context_text — added by the handler
  for convertible formats with a valid CFI); PUT progress binds
  sync.SaveProgressRequest and returns database.ReadingProgress
- Beam's examples were missing entirely on 4 files (list/search/progress
  GET/PUT) — relabeled existing fences or inserted contract-shaped blocks

Gate-driven merge scripts (object + array variants) brought all examples to
the exact handler key sets. make test 9/9.

2026-10-24 16:09:38 -04:00

1.4 KiB

Raw Blame History

method, path, auth, area

method	path	auth	area
PUT	/api/media-items/:id/rating	jwt	media-items

Update Rating

Update an existing rating for a media item.

Endpoint: PUT /api/media-items/{media_id}/rating Auth: Required Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
media_id	string	Yes	Media item UUID

Request Body

Field	Type	Required	Description
rating	integer	Yes	Rating value (1-10 scale)
review	string	No	Optional review text

Rating Scale: 1-10 (odd numbers = half-stars: 1=0.5★, 2=1★, 3=1.5★, ..., 9=4.5★, 10=5★)

Example Request

{
  "rating": 8,
  "review": "Great book! Very enjoyable read."
}

Response (200 OK)

{
  "id": "uuid",
  "media_item_id": "uuid",
  "user_id": "uuid",
  "rating": 8,
  "created_at": "2026-01-31T10:00:00Z",
  "updated_at": "2026-01-31T11:00:00Z"
}

Error Responses

Code	Description
400	Invalid request data
401	Invalid or expired token
404	Media item or rating not found

1.4 KiB Raw Blame History