Ammendments Amended Endpoints — what the feed release changes in endpoints you already have Author : Josh S. Sakweli, Backend Lead Team Last Updated : 2026-09-18 Version : v1.0 (backend branch fet/feed_baking ) Base URL : https://dev.api.nexgate.co (staging) · https://api.nexgate.co (production) Short Description : This document lists only the endpoints that already existed and have now changed . Nothing here is a new URL. Every path below is one your app already calls today, and every entry says exactly what moved under it, whether the change is visible in the response, and whether you have to do anything about it. Its sibling document is 09_NEW_ENDPOINTS.md — the endpoints and controllers that did not exist before (home feed, reels, marketplace, events, interactions, and the admin/ops APIs). If a path is not in this file, it was not amended; if it is not in that file, it is not new. Hints : No path, verb or field was removed. Every change is additive, a bug fix, or a stricter parameter. Two response fields were added (both on ClipResponse ). An app that ignores them behaves exactly as it does today. Three endpoints return fewer items than before for some viewers . That is the point: they were leaking private content. Four old paths are being deleted, not migrated from — see Old endpoints being deleted . There is no production data and no grace period: when the frontend has switched, they go. Search this file by path. Every heading is the literal URL. How to read this document Each entry carries two chips. Change type — what kind of amendment it is: Chip Meaning SECURITY FIX The endpoint used to return content the viewer was not allowed to see RESPONSE A field was added, or a field that used to be empty is now filled BEHAVIOUR Same shape, different contents, ordering or side effect PARAMS A query parameter is now validated or clamped BEING DELETED Still answers today, but is scheduled for removal — do not build on it App action — what the frontend must do: Chip Meaning 🟢 None Ships safely with no app change 🟡 Optional Works untouched, but there is something worth picking up 🔴 Required The app must handle this or it will misbehave Index # Endpoint Change type App action 1 GET /api/v1/e-social/feed RESPONSE · BEING DELETED 🔴 Required 2 GET /api/v1/e-social/clip/feed SECURITY FIX · RESPONSE · BEHAVIOUR 🔴 Required 3 GET /api/v1/e-social/clip/{mediaId} SECURITY FIX · RESPONSE 🟡 Optional 4 GET /api/v1/e-social/clip/user/{userId}/videos SECURITY FIX · RESPONSE · BEHAVIOUR 🔴 Required 5 POST /api/v1/e-social/clip/{mediaId}/view BEHAVIOUR 🟡 Optional 6 GET /api/v1/e-social/hashtags/{hashtag}/posts SECURITY FIX · PARAMS · BEHAVIOUR · RESPONSE 🟢 None 7 GET /api/v1/e-social/hashtags/trending BEHAVIOUR · PARAMS 🟢 None 8 GET /api/v1/e-social/hashtags/search BEHAVIOUR · PARAMS 🟢 None Standard Response Format Unchanged. Every endpoint below still answers in the usual envelope: { "success": true, "httpStatus": "OK", "message": "Operation completed successfully", "action_time": "2026-09-18T10:30:45", "data": { } } Errors are unchanged too: 400 bad request, 401 token problems, 403 permission, 404 not found, 422 validation, 500 server. Where an amendment introduces a new reason for an existing status, the entry says so. Endpoints 1. Home feed (old) Endpoint : GET /api/v1/e-social/feed Change type : RESPONSE BEING DELETED · App action : 🔴 Required — move to /api/v1/feed/home This endpoint is going away. It is listed here because it still answers today and its contents changed. Do not build anything new on it. Access Level : 🔒 Protected · Authentication : Authorization: Bearer What changed a) topComments is now always populated. This endpoint used to call the post mapper with "no top comments", so topComments came back empty on every post. The mapper now always fills it (up to 5, most-liked first) because the feed needs it and loading it costs nothing extra in the batched mapper. b) A backend switch can make it answer from the new pipeline. There is a feed.legacy.fromPipeline setting that makes this endpoint serve the new feed in the old shape. It was built for a migration that is no longer needed, and it is not part of the plan — it will be deleted together with the endpoint. Mentioned only so nobody is surprised to find it in the code. Response shape (unchanged) { "success": true, "httpStatus": "OK", "message": "Feed retrieved", "action_time": "2026-09-18T10:30:45", "data": { "posts": [ { "postId": "…", "topComments": [ { } ] } ], "unseenCount": 12, "nextCursor": "eyJ0IjoxNzU4…" } } What the app must do Move to GET /api/v1/feed/home . See 09_NEW_ENDPOINTS.md A1 and 07_FEED_ENDPOINTS_GUIDE.md . This path is deleted once you have. Until then it keeps working as it does today. 2. Clip feed Endpoint : GET /api/v1/e-social/clip/feed Change type : SECURITY FIX RESPONSE BEHAVIOUR · App action : 🔴 Required Access Level : 🔒 Protected · Authentication : Authorization: Bearer What changed a) It no longer leaks private videos. The feed used to return clips from followers-only and mentions-only posts to anyone, and clips from accounts the viewer had blocked. It now filters by the post's visibility, the viewer's follow relationship, mentions, and blocks — in the database, before paging. b) Moderation labels apply. A clip whose post or author carries a moderation label is either dropped from the page or marked for an interstitial, per the rules in 01_ARCHITECTURE.md §9.2. Followers are treated more leniently than strangers. c) Two new fields in each clip (see the table below). d) A page can be shorter than limit while hasMore is still true . The cursor is taken from the last row the database returned, before labels remove anything. So clips.length < limit no longer means "end of feed" — only hasMore === false and nextCursor === null mean that. e) limit is clamped to 1–20 (it was previously used as given). Query Parameters Parameter Type Required Description Validation Default cursor string No Opaque page cursor from the previous response Invalid cursor → 400 none (first page) limit integer No Clips per page Clamped to 1–20 (new) 10 New response fields Field Type Values Description visibility string ALLOW , INTERSTITIAL INTERSTITIAL means: do not autoplay. Show a "sensitive content — tap to view" cover first. Defaults to ALLOW media.durationMs integer milliseconds Clip length. Useful for the progress bar, and needed to report watch time correctly in the interactions batch Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "Clip feed fetched", "action_time": "2026-09-18T10:30:45", "data": { "clips": [ { "postId": "4f2a77e1-0c8b-4d2f-9a11-7b6c3e5d8f90", "visibility": "ALLOW", "media": { "id": "9b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "durationMs": 14200, "variants": { "hls": "https://…/master.m3u8", "thumb": "https://…/thumb.jpg" } }, "engagement": { }, "userInteraction": { } } ], "nextCursor": "MjAyNi0wOS0xN1QxMDoyMjozMTo0ZjJh…", "hasMore": true } } What the app must do Stop using clips.length < limit as the end-of-feed test. Use hasMore . Honour visibility . INTERSTITIAL clips must not autoplay behind no cover. Expect fewer clips than before for some viewers. That is correct, not a regression. 3. Single clip Endpoint : GET /api/v1/e-social/clip/{mediaId} Change type : SECURITY FIX RESPONSE · App action : 🟡 Optional Access Level : 🔒 Protected · Authentication : Authorization: Bearer What changed A clip the viewer may not see now returns 404 , with the message Clip not found . It used to be returned in full to anyone holding the id. This covers followers-only and mentions-only posts, blocked authors, and clips dropped by a moderation label. Same two new fields as the feed: visibility and media.durationMs . Error Response JSON Sample { "success": false, "httpStatus": "NOT_FOUND", "message": "Clip not found", "action_time": "2026-09-18T10:30:45", "data": "Clip not found" } What the app should do Treat 404 here as "this clip is gone or not for you" and return the user to the previous screen — it is no longer safe to assume a 404 means deleted. 4. A user's videos Endpoint : GET /api/v1/e-social/clip/user/{userId}/videos Change type : SECURITY FIX RESPONSE BEHAVIOUR · App action : 🔴 Required Access Level : 🔒 Protected · Authentication : Authorization: Bearer What changed Exactly the same three things as the clip feed (entry 2), on a profile's video grid: private and blocked-author videos are filtered out; a viewer looking at someone else's profile now sees only what they are entitled to (the owner still sees their own); visibility and media.durationMs added; short pages with hasMore: true are possible, and limit is clamped to 1–20 (default 12). What the app must do Use hasMore , not the page length, to decide whether to load more in the profile grid. 5. Record a clip view Endpoint : POST /api/v1/e-social/clip/{mediaId}/view Change type : BEHAVIOUR · App action : 🟡 Optional Access Level : 🔒 Protected · Authentication : Authorization: Bearer Response : still 204 No Content , still no body. The request contract has not changed. What changed A view is now counted once per viewer , cheaply, in Redis. Repeat calls from the same viewer are accepted and ignored instead of inflating the count. The clip_views table is no longer written. Per-view rows are gone; the counter is what survives. The request body is accepted and ignored. Watch time does not belong here — it belongs in the interactions batch, where the recommendation model can read it ( 05_INTERACTIONS_CLIENT_GUIDE.md ). What the app should do Keep calling this for the view counter, and send watch time as a VIEW event with watchMs and mediaDurationMs to POST /api/v1/feed/interactions/batch . Anything sent in this body is thrown away. 6. Posts for a hashtag Endpoint : GET /api/v1/e-social/hashtags/{hashtag}/posts Change type : SECURITY FIX PARAMS BEHAVIOUR RESPONSE · App action : 🟢 None Access Level : 🌐 Public (a signed-in viewer sees more) · Authentication : optional bearer token What changed a) It no longer leaks private posts. The old version loaded every post id carrying the tag into memory and checked only "published and not deleted" — so followers-only and mentions-only posts reached anyone who opened the tag page. Visibility, mentions and blocks are now enforced in the database query itself. b) Paging is real. The whole tag is no longer loaded into memory; the page and its total count are computed in the database. c) Ordering is by published_at descending (it was createdAt ). For a scheduled post these differ: the post now sorts by when it went live, which is what a reader expects. d) page and size are clamped instead of being trusted. e) topComments is now populated on each post, for the same reason as entry 1. f) Hashtags are matched in any script. Tags are normalised the same way at write and read time, so non-Latin tags (Swahili, Arabic, CJK …) now match instead of silently returning nothing. Query Parameters Parameter Type Required Description Validation Default filter enum No ALL , PRODUCTS , SHOPS , EVENTS unknown value → 400 ALL page integer No 1-based page number Below 1 is treated as 1 (new) 1 size integer No Posts per page Clamped to 1–50 (new) 20 What the app should do Nothing. Expect a signed-out viewer to see fewer posts than a signed-in one, and a blocked author's posts never to appear. 7. Trending hashtags Endpoint : GET /api/v1/e-social/hashtags/trending Change type : BEHAVIOUR PARAMS · App action : 🟢 None Access Level : 🌐 Public · Authentication : none Response shape : unchanged — a list of { hashtag, posts } . What changed a) Trending is now hard to game. Tags are ranked by how many different accounts used them, then by how many posts. One account posting the same tag fifty times counts once, and #sale #sale inside one post counts once. b) Private and draft posts never count. Only public, published, non-deleted posts inside the window — so a private post can no longer push its tag onto a public page. c) Results are cached for 5 minutes per window. The page is public and read far more often than it changes. Query Parameters Parameter Type Required Description Validation Default window string No 24h , 7d , 30d . Anything else is treated as 24h — 24h limit integer No How many tags Clamped to 1–50 (new) 15 8. Hashtag suggestions (type-ahead) Endpoint : GET /api/v1/e-social/hashtags/search Change type : BEHAVIOUR PARAMS · App action : 🟢 None Access Level : 🌐 Public · Authentication : none Response shape : unchanged — a list of { hashtag, posts } . What changed Answered from a Redis suggestion index , not from the database. The old query scanned and grouped the entire post_hashtags table on every keystroke . Suggestions come from public posts only. Tags that exist only on drafts or private posts are no longer suggested. limit is clamped to 1–20 (default 5). An empty or blank q returns an empty list instead of an error. Query Parameters Parameter Type Required Description Validation Default q string Yes What the user has typed so far Blank → empty list — limit integer No How many suggestions Clamped to 1–20 (new) 5 Old endpoints being deleted There is no migration and no grace period. This is a staging platform with no production users and no data worth keeping — the database will be dropped. So these paths are not being "migrated away from" over time; they are deleted from the codebase in one commit , as soon as the frontend confirms it has switched. What that means for you: There is no fallback . Once the commit lands, these paths return 404 . There is no dual-running period to lean on, and no backend flag that will quietly keep them alive. Tell the backend team when your calls have moved. The deletion happens on that word. The strings below are literal — copy them into your project search to find every call site. Search for this What it is Replace with Notes api/v1/e-social/feed Old home feed api/v1/feed/home Response shapes differ — see 09 A1 api/v1/e-social/feed/stream Feed SSE stream nothing — use api/v1/events The chat/events stream now carries a feed.new hint; on receiving it, call api/v1/feed/home/has-new api/v1/e-social/feed/heartbeat SSE keep-alive nothing Dies with the stream above api/v1/e-social/clip/feed Clip feed api/v1/feed/reels Still amended in the meantime (entry 2), so it behaves correctly right up to the day it goes Not going anywhere — keep calling these: api/v1/e-social/clip/{mediaId} , api/v1/e-social/clip/{mediaId}/view , api/v1/e-social/clip/user/{userId}/videos , and all three api/v1/e-social/hashtags/… endpoints. A one-liner for a frontend repo: grep -rn "e-social/feed\|e-social/clip/feed" src/ --include=*.{ts,tsx,js,jsx,dart,kt,swift} Every hit is a call site that must move. When that grep returns nothing, tell the backend team — that is the signal to delete. What did not change Worth stating plainly, so nobody goes looking: No existing response field was renamed or removed , anywhere. PostResponse is unchanged. Post, profile, search, bookmark and comment endpoints return exactly what they returned before. They are faster (a page of posts went from about 242 database queries to about 24) and they load the viewer's account once instead of twice, but the JSON is the same. Engagement numbers (likes, views, comments) keep the same field names. Some values were recounted and corrected as part of an earlier release. No new notification is produced by any endpoint in this document. Authentication, the response envelope and every error code behave as before. Related documents Doc What it covers 09_NEW_ENDPOINTS.md Every new endpoint and new controller 07_FEED_ENDPOINTS_GUIDE.md The app team's walkthrough of the new feed screens 05_INTERACTIONS_CLIENT_GUIDE.md What the app must report back, and exact action definitions 01_ARCHITECTURE.md The design. §A.3 is the migration and the deletion list; §9.2 is the label rule New Endpoints — everything the feed release adds Author : Josh S. Sakweli, Backend Lead Team Last Updated : 2026-09-18 Version : v1.0 (backend branch fet/feed_baking ) Base URL : https://dev.api.nexgate.co (staging) · https://api.nexgate.co (production) Short Description : Every endpoint here is new — a new URL on a new controller. Nothing in this document replaces a field or changes an existing response. It is in two parts: Part A is what the apps call (the five feed surfaces and the interactions endpoint), Part B is what the admin panel and the operations team call (sponsored slots, business rules, moderation labels, interest mapping, backfills and the per-account debug trace). Its sibling document is 08_AMENDED_ENDPOINTS.md — the endpoints you already have that changed behaviour. If a path is in this file it did not exist before; if it is in that file it is not new. Hints : Every endpoint needs Authorization: Bearer . There are no public endpoints here. Part B additionally needs an admin role, and says which one per endpoint. The five feed surfaces share one contract: feedSessionId + items[] + nextCursor . Learn it once. nextCursor: null means "nothing more right now" — not "never again". Pull-to-refresh starts a new session. Feed surfaces never fail loudly. If the recommendation service or Redis is down you get a simpler feed, not an error. Reporting back is not optional: a feed you do not report on cannot learn. See 05_INTERACTIONS_CLIENT_GUIDE.md . How this document is organised Part Who calls it Controllers 🅰️ Part A — App-facing Android, iOS, web HomeFeedController , ReelsFeedController , MarketFeedController , EventsFeedController , FeedListsController , InteractionController 🅱️ Part B — Admin & operations Admin panel, ops PromotionAdminController , LabelAdminController , InterestAdminController , FeedBackfillController Each entry carries an access chip: Chip Meaning 🔒 User Any signed-in account 🛡️ Admin ROLE_SUPER_ADMIN or ROLE_STAFF_ADMIN 🛡️ Super admin ROLE_SUPER_ADMIN only Index Part A — App-facing # Endpoint Purpose Replaces A1 GET /api/v1/feed/home The home feed: posts and products api/v1/e-social/feed A2 GET /api/v1/feed/home/has-new The "new posts" bubble the feed SSE stream A3 GET /api/v1/feed/reels The reels feed api/v1/e-social/clip/feed A4 GET /api/v1/feed/marketplace Marketplace "For You" — A5 GET /api/v1/feed/events Events "For You" — A6 GET /api/v1/feed/products/{productId}/similar "Similar items" on a product page — A7 GET /api/v1/feed/shops/suggested "Shops you might like" — A8 POST /api/v1/feed/interactions/batch Report what the user did — Part B — Admin & operations # Endpoint Purpose Role B1 POST /api/admin/feed/sponsored Start a sponsored campaign Admin B2 GET /api/admin/feed/sponsored List active campaigns Admin B3 DELETE /api/admin/feed/sponsored/{id} Stop a campaign Admin B4 POST /api/admin/feed/business-rules Boost or suppress something for a period Admin B5 GET /api/admin/feed/business-rules List running and upcoming rules Admin B6 DELETE /api/admin/feed/business-rules/{id} End a rule now Admin B7 GET /api/admin/feed/debug/{accountId} Why this person saw this feed Admin B8 POST /api/admin/feed/labels Label a post, product, shop or account Admin B9 DELETE /api/admin/feed/labels/{labelId} Remove a label Admin B10 GET /api/admin/feed/labels Labels on one target, with history Admin B11 GET /api/admin/feed/interests The interest list and every mapping Admin B12 GET /api/admin/feed/interests/unmapped What still needs mapping Admin B13 PUT /api/admin/feed/interests/product-categories/{categoryId} Map a product category Admin B14 PUT /api/admin/feed/interests/event-categories/{categoryId} Map an event category Admin B15 PUT /api/admin/feed/interests/hashtags/{hashtag} Map a hashtag Admin B16 POST /api/admin/feed/backfills Republish existing data into the feed Super admin B17 GET /api/admin/feed/backfills Recent backfill runs Super admin B18 POST /api/admin/feed/backfills/{runId}/cancel Stop a run Super admin Standard Response Format Same envelope as the rest of the platform. { "success": true, "httpStatus": "OK", "message": "Home feed", "action_time": "2026-09-18T10:30:45", "data": { } } { "success": false, "httpStatus": "NOT_FOUND", "message": "No active campaign 42", "action_time": "2026-09-18T10:30:45", "data": "No active campaign 42" } Errors used in this document : 400 bad request (a rule or campaign that makes no sense, an unknown label, an unknown backfill aggregate), 401 missing/expired token, 403 wrong role, 404 not found (unknown id, unknown surface, no debug trace), 422 validation failure with a field map, 500 server error. Part A — App-facing The shared feed contract A4, A5, A1 and A3 all answer with the same three things: Field Type Description feedSessionId string The session this page came from. Send it back in every interaction as context.feedSessionId — it is how a like is tied to the feed that showed the item items array The items, already in display order nextCursor string | null Pass it as cursor for the next page. null = nothing more right now And every item carries: Field Type Description position integer The item's place in the feed, from 0. Send it back as context.position source string Why this item is here. Send it back as context.source visibility string ALLOW , or INTERSTITIAL → show a "sensitive content, tap to view" cover before the media source values : FOLLOWING , CELEBRITY , RECO , INTEREST , FALLBACK , SPONSORED , TRENDING , SEARCH . Do not invent others — the interactions endpoint rejects unknown ones. A1. Home feed Purpose : The main feed. Mixes posts from people the user follows, recommended posts, and products. Endpoint : GET /api/v1/feed/home Access : 🔒 User · Authentication : Authorization: Bearer Replaces : api/v1/e-social/feed Query Parameters Parameter Type Required Description Validation Default cursor string No Cursor from the previous page. Omit for the first page, and omit on pull-to-refresh to start a new session opaque none limit integer No Items per page clamped to 1–30 15 Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "Home feed", "action_time": "2026-09-18T10:30:45", "data": { "feedSessionId": "fs-77aa31c8", "items": [ { "type": "POST", "position": 0, "source": "FOLLOWING", "visibility": "ALLOW", "post": { "postId": "4f2a77e1-0c8b-4d2f-9a11-7b6c3e5d8f90" }, "product": null }, { "type": "PRODUCT", "position": 1, "source": "RECO", "visibility": "ALLOW", "post": null, "product": { "productId": "8c31a0d2-77e4-4b1a-9f3c-2d5e6a7b8c90" } } ], "nextCursor": "eyJzIjoiZnMtNzdhYTMxYzgiLCJwIjoxNX0" } } Success Response Fields Field Description items[].type POST or PRODUCT . Exactly one of post / product is filled; the other is null items[].post A full PostResponse — the same object the rest of the API returns for a post items[].product A ProductSummaryResponse — the same object the marketplace list returns Notes The feed is built once per session and paged from it, so a page read is fast and the order is stable while the user scrolls. Items are filtered again at page-read time, so something deleted, blocked or muted mid-scroll does not appear. If the feed store is unavailable the user gets a simpler feed from recent posts, never an error. A2. New posts available ("the bubble") Purpose : Tells the app whether to show the "N new posts" bubble at the top of the home feed. Endpoint : GET /api/v1/feed/home/has-new Access : 🔒 User · Authentication : Authorization: Bearer Replaces : the old feed SSE stream ( api/v1/e-social/feed/stream ) Query Parameters Parameter Type Required Description Validation since integer Yes publishedAt of the newest post the app is currently showing, as epoch milliseconds must parse as a long Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "New posts", "action_time": "2026-09-18T10:30:45", "data": { "count": 7, "more": false, "authors": [ { "accountId": "…", "userName": "mariam", "profileMedia": { } } ], "nextPollIn": 300 } } Success Response Fields Field Description count How many new posts, capped at 20 more true when there were more than 20 — show "20+" authors Up to 3 authors, for the avatars on the bubble nextPollIn Seconds to wait before asking again. Read this from the response, do not hard-code it — the server lengthens it under load, with no app release When to call it Moment Action Feed comes on screen Call once Feed stays on screen Call again after nextPollIn seconds A feed.new event arrives on the /api/v1/events stream Call immediately count > 0 and the user has scrolled down Show the bubble count > 0 and the user is already at the top No bubble — fetch and insert the posts Bubble tapped Call GET /api/v1/feed/home with no cursor and prepend the result above the existing list The feed.new event. The existing chat/events stream now carries an event named feed.new with an empty body on the account's personal channel. It carries no posts and no count — it only means "call has-new now". It is throttled to at most one a minute, and it is an optimisation: if the stream is down, the next poll finds the posts anyway. A3. Reels feed Purpose : The vertical clip feed. Endpoint : GET /api/v1/feed/reels Access : 🔒 User · Authentication : Authorization: Bearer Replaces : api/v1/e-social/clip/feed Query Parameters Parameter Type Required Description Validation Default cursor string No Cursor from the previous page opaque none limit integer No Clips per page clamped to 1–30 10 Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "Reels", "action_time": "2026-09-18T10:30:45", "data": { "feedSessionId": "fs-91bd4410", "items": [ { "position": 0, "source": "RECO", "clip": { "postId": "…", "visibility": "ALLOW", "media": { "id": "…", "durationMs": 14200, "variants": { "hls": "https://…/master.m3u8" } } } } ], "nextCursor": "eyJzIjoiZnMtOTFiZDQ0MTAiLCJwIjoxMH0" } } Notes clip is the same ClipResponse the existing clip screen already renders — the reels screen does not need a new renderer. Here visibility sits on the clip , not on the item wrapper. Reels have their own "already served" memory: scrolling reels does not use up the home feed, and vice versa. A4. Marketplace "For You" Purpose : A personalised product feed for the marketplace tab. Endpoint : GET /api/v1/feed/marketplace Access : 🔒 User · Authentication : Authorization: Bearer Query Parameters Parameter Type Required Description Validation Default cursor string No Cursor from the previous page opaque none limit integer No Products per page clamped to 1–30 20 Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "Marketplace for you", "action_time": "2026-09-18T10:30:45", "data": { "feedSessionId": "fs-2210ab7e", "items": [ { "position": 0, "source": "RECO", "visibility": "ALLOW", "product": { "productId": "…" } }, { "position": 1, "source": "SPONSORED", "visibility": "ALLOW", "product": { "productId": "…" } } ], "nextCursor": null } } source here means : RECO (the model), FOLLOWING (a shop the user subscribes to), SPONSORED (a paid slot — label it in the UI), FALLBACK (trending, new shops, or products seen in posts). A5. Events "For You" Purpose : Event discovery. Endpoint : GET /api/v1/feed/events Access : 🔒 User · Authentication : Authorization: Bearer Query Parameters Parameter Type Required Description Validation Default cursor string No Cursor from the previous page opaque none limit integer No Events per page clamped to 1–30 20 Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "Events for you", "action_time": "2026-09-18T10:30:45", "data": { "feedSessionId": "fs-55c0d913", "items": [ { "position": 0, "source": "FOLLOWING", "visibility": "ALLOW", "event": { "eventId": "…" } } ], "nextCursor": "eyJzIjoiZnMtNTVjMGQ5MTMiLCJwIjoyMH0" } } source here means : RECO , FOLLOWING (an organiser the user follows), FALLBACK (upcoming events, by bookings). event is the usual EventSummaryResponse . A6. Similar items Purpose : The "Similar items" strip on a product page. Endpoint : GET /api/v1/feed/products/{productId}/similar Access : 🔒 User · Authentication : Authorization: Bearer Path Parameters Parameter Type Required Description productId UUID Yes The product being viewed Query Parameters Parameter Type Required Description Validation Default limit integer No How many products clamped to 1–50 20 Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "Similar items", "action_time": "2026-09-18T10:30:45", "data": { "items": [ { "source": "RECO", "visibility": "ALLOW", "product": { "productId": "…" } }, { "source": "CATEGORY", "visibility": "ALLOW", "product": { "productId": "…" } } ] } } No paging and no feedSessionId — this is a strip, not a feed. source is RECO (the model's similar items) or CATEGORY (best sellers of the same category, used when the model has nothing). A7. Suggested shops Purpose : The "Shops you might like" strip. Endpoint : GET /api/v1/feed/shops/suggested Access : 🔒 User · Authentication : Authorization: Bearer Query Parameters Parameter Type Required Description Validation Default limit integer No How many shops clamped to 1–30 10 Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "Suggested shops", "action_time": "2026-09-18T10:30:45", "data": { "items": [ { "source": "NEW", "shopId": "…", "shopName": "Kilimanjaro Coffee", "shopSlug": "kilimanjaro-coffee", "shopDescription": "Single-origin roasters", "logo": { }, "isVerified": true, "city": "Arusha", "region": "Arusha", "subscriberCount": 1284 } ] } } source : RECO , NEW (opened in the last 30 days) or POPULAR (most subscribers). No contact details are returned — the viewer does not follow this shop yet. A8. Report interactions Purpose : Send what the user did, in batches. This is the only way the recommendation model learns. Endpoint : POST /api/v1/feed/interactions/batch Access : 🔒 User · Authentication : Authorization: Bearer Success status : 202 Accepted Full definitions of every action live in 05_INTERACTIONS_CLIENT_GUIDE.md . That document is the contract; this entry is the reference. What your batch becomes once the backend has it is 10_EVENT_CATALOGUE.md §5. This is the only endpoint on the whole platform that puts anything on the event stream from the app. Everything else the model learns — posts, products, shops, events, profiles, follows, blocks, orders, wishlists, and even likes and purchases — is published automatically from committed database rows. The app never announces that something exists or changed; it only reports what it alone can see: impressions, views, watch time, skips, clicks and searches. Request JSON Sample { "sessionId": "s-8812e0c4", "client": { "platform": "ANDROID", "appVersion": "2.4.1", "networkType": "CELLULAR" }, "events": [ { "clientEventId": "c-000184", "action": "IMPRESSION", "targetType": "POST", "targetId": "4f2a77e1-0c8b-4d2f-9a11-7b6c3e5d8f90", "occurredAt": "2026-09-18T10:22:31.900Z", "context": { "surface": "REELS", "position": 3, "feedSessionId": "fs-77aa", "source": "RECO" } }, { "clientEventId": "c-000185", "action": "VIEW", "targetType": "POST", "targetId": "4f2a77e1-0c8b-4d2f-9a11-7b6c3e5d8f90", "occurredAt": "2026-09-18T10:22:41.100Z", "watchMs": 9000, "mediaDurationMs": 6000, "loopCount": 1, "soundOn": true, "mediaIndex": 0, "context": { "surface": "REELS", "position": 3, "feedSessionId": "fs-77aa", "source": "RECO" } } ] } Request Body Parameters Parameter Type Required Description Validation sessionId string No The app session — client.platform string No ANDROID , IOS , WEB enum client.appVersion string No e.g. 2.4.1 — client.networkType string No WIFI , CELLULAR , OFFLINE , UNKNOWN enum events array Yes The batch max 100 per request events[].clientEventId string Yes Your own id, unique within the batch max 64 chars events[].action string Yes See the action table below enum events[].targetType string Yes* POST , PRODUCT , SHOP , EVENT , PROFILE *not required for SEARCH events[].targetId string Yes* UUID of the target must be a UUID events[].occurredAt string Yes When it happened, on the device ISO 8601 events[].dwellMs / watchMs integer No Time on screen / watched 0 – 6 h events[].mediaDurationMs integer No Length of the media 0 – 12 h events[].loopCount integer No Replays 0 – 1000 events[].soundOn boolean No Was sound on — events[].mediaIndex integer No Which item of a carousel 0 – 100 events[].context.surface string No FEED , REELS , SEARCH , PRODUCT_PAGE , SHOP_PAGE , EVENT_PAGE , PROFILE_PAGE , RECOMMENDATION , NOTIFICATION , CHAT enum events[].context.position integer No The item's position in the feed — events[].context.feedSessionId string No From the feed response — events[].context.source string No From the item enum events[].context.viaPostId string No The post a product was reached through UUID events[].context.query string No The search text, for SEARCH — Unknown fields are ignored , deliberately: a newer app adding a field must never lose the batch. Actions the app sends IMPRESSION , VIEW , SKIP , CLICK , SEARCH , NOT_INTERESTED , HIDE . Actions the app must NOT send LIKE , UNLIKE , SHARE , BOOKMARK , COMMENT , ADD_TO_CART , REMOVE_FROM_CART , PURCHASE , BLOCK , REPORT , MUTE_AUTHOR . The backend sends these itself when the change commits, so an app that also sent them would count every like twice. They come back rejected with SENT_BY_SERVER . Call the normal feature API (the like endpoint, the cart endpoint) and the interaction is recorded for you. Success Response JSON Sample { "success": true, "httpStatus": "ACCEPTED", "message": "Interactions received", "action_time": "2026-09-18T10:30:45", "data": { "accepted": 2, "dropped": 0, "rejected": [] } } Field Description accepted Kept dropped Valid but not kept (rate limit, or the event log was briefly unavailable). Do not resend — these are signal, not records rejected Invalid. Do not resend. Each entry is { clientEventId, reason } — a rejection is a bug in the app; log it in debug builds Rejection reasons CLIENT_EVENT_ID_REQUIRED_MAX_64 , UNKNOWN_ACTION , SENT_BY_SERVER , UNKNOWN_TARGET_TYPE , TARGET_ID_NOT_UUID , DUPLICATE_CLIENT_EVENT_ID , OCCURRED_AT_NOT_ISO_8601 , DURATION_OUT_OF_RANGE , LOOP_COUNT_OUT_OF_RANGE , MEDIA_INDEX_OUT_OF_RANGE , UNKNOWN_SURFACE , UNKNOWN_SOURCE , POSITION_OUT_OF_RANGE , VIA_POST_ID_NOT_UUID , BATCH_LIMIT_100 , EMPTY_EVENT . Part B — Admin & operations Everything below is on /api/admin/feed . A signed-in account without the role gets 403 . Sponsored campaigns A sponsored campaign places one product at fixed slots in home and marketplace sessions, while it is inside its window. A viewer sees the same campaign at most feed.sponsored.capPerDay times in 24 hours (a feed_params setting), so a campaign cannot follow someone down the page. Campaigns and rules are re-read from the database at most every 60 seconds , so a change can take up to a minute to show up in feeds. Not built yet : billing, budgets and self-serve. A campaign today is created by staff and runs between two dates, free. B1. Start a campaign Endpoint : POST /api/admin/feed/sponsored · Access : 🛡️ Admin Request JSON Sample { "productId": "8c31a0d2-77e4-4b1a-9f3c-2d5e6a7b8c90", "startsAt": "2026-10-01T00:00:00Z", "endsAt": "2026-10-15T00:00:00Z" } Parameter Type Required Validation productId UUID Yes the product must exist, else 400 Product not found startsAt ISO 8601 instant Yes — endsAt ISO 8601 instant Yes must be after startsAt , else 400 endsAt must be after startsAt Success Response { "success": true, "httpStatus": "OK", "message": "Campaign added", "action_time": "2026-09-18T10:30:45", "data": { "id": 42, "productId": "8c31a0d2-…", "startsAt": "2026-10-01T00:00:00Z", "endsAt": "2026-10-15T00:00:00Z", "active": false } } active is true only while the campaign is inside its window. B2. List campaigns Endpoint : GET /api/admin/feed/sponsored · Access : 🛡️ Admin Returns an array of the object above — running and upcoming campaigns. B3. Stop a campaign Endpoint : DELETE /api/admin/feed/sponsored/{id} · Access : 🛡️ Admin Parameter Type Required Description id integer Yes The campaign id from B1/B2 Ends it immediately. An id that is not an active campaign gives 404 No active campaign {id} . Business rules A business rule multiplies the feed score of everything matching it, for a period. It is the lever for "push this category this week" or "quieten this shop while we investigate" — without touching code. Several matching rules multiply together , and like campaigns they are re-read at most every 60 seconds. B4. Add a rule Endpoint : POST /api/admin/feed/business-rules · Access : 🛡️ Admin Request JSON Sample { "matchType": "CATEGORY", "matchValue": "b81d9a34-5f2c-4c7e-9a10-3e5d7f9b1c22", "multiplier": 1.4, "startsAt": "2026-10-01T00:00:00Z", "endsAt": "2026-10-08T00:00:00Z" } Parameter Type Required Description Validation matchType string Yes PRODUCT , SHOP , CATEGORY (all three match products) or ACCOUNT (matches posts by, and events organised by, that account) enum matchValue string Yes The id of that product / shop / category / account 36-character UUID multiplier number Yes Above 1 boosts, below 1 suppresses 0.1 – 3.0 startsAt ISO 8601 instant Yes — — endsAt ISO 8601 instant Yes — must be after startsAt Success Response { "success": true, "httpStatus": "OK", "message": "Rule added", "action_time": "2026-09-18T10:30:45", "data": { "id": 17, "matchType": "CATEGORY", "matchValue": "b81d9a34-…", "multiplier": 1.4, "startsAt": "2026-10-01T00:00:00Z", "endsAt": "2026-10-08T00:00:00Z" } } B5. List rules Endpoint : GET /api/admin/feed/business-rules · Access : 🛡️ Admin Running and upcoming rules, as an array of the object above. Expired rules are not listed. B6. End a rule now Endpoint : DELETE /api/admin/feed/business-rules/{id} · Access : 🛡️ Admin 404 No running or upcoming rule {id} if it has already finished. B7. Why did this person see this feed? Purpose : The per-account debug trace. For support and for tuning: it shows every item the last feed build produced, and every item it threw away and why . Endpoint : GET /api/admin/feed/debug/{accountId} · Access : 🛡️ Admin Path & Query Parameters Parameter Type Required Description Default accountId UUID Yes Whose feed — surface string No HOME , REELS , MARKET , EVENTS HOME How to switch it on Tracing is off unless the account is listed. Add the account id to the feed.debug.accounts row in the feed_params table, then have that person (or a test account) open the feed. The trace is kept for 1 hour . Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "Last session trace", "action_time": "2026-09-18T10:30:45", "data": { "surface": "HOME", "builtAt": 1789412345678, "shown": [ { "position": 0, "type": "POST", "id": "4f2a77e1-…", "source": "FOLLOWING", "baseScore": 1.81, "score": 2.35, "visibility": "ALLOW", "trace": ["NewShopBoost x1.3"] } ], "removed": [ { "type": "POST", "id": "9b10…", "source": "FALLBACK", "filter": "Seen" } ] } } Errors Status When 404 Unknown surface {x} surface is not one of the four 404 No trace: add the account to feed_params 'feed.debug.accounts', then open that feed (kept 1 h) Tracing was off, or the trace expired Moderation labels A label is a moderation outcome attached to a post, product, shop or account. The feed reads labels; it has no special cases of its own. Labels do not delete anything — they decide who stops seeing it. The rule (first match wins, and strangers are treated more strictly than followers, because following was the user's choice and discovery is ours): Label Viewer follows the author Viewer does not follow suspended (account or item), prohibited_item removed removed counterfeit_suspected shown removed spam_suspected (account) shown removed reported_threshold shown removed low_quality_media shown removed sensitive_media shown behind a cover ( INTERSTITIAL ) removed reported_threshold is applied automatically when a post passes the report threshold. The rest are applied by staff, by a rule, or by a model. B8. Add a label Endpoint : POST /api/admin/feed/labels · Access : 🛡️ Admin Request JSON Sample { "targetType": "POST", "targetId": "4f2a77e1-0c8b-4d2f-9a11-7b6c3e5d8f90", "label": "sensitive_media", "expiresInHours": 72 } Parameter Type Required Description Validation targetType string Yes POST , PRODUCT , SHOP , ACCOUNT else 400 Unknown target type targetId UUID Yes What to label — label string Yes suspended , spam_suspected , counterfeit_suspected , sensitive_media , prohibited_item , reported_threshold , low_quality_media else 400 Unknown label '…' expiresInHours integer No Omit for a permanent label must be positive B9. Remove a label Endpoint : DELETE /api/admin/feed/labels/{labelId} · Access : 🛡️ Admin 404 if that label id does not exist. B10. Labels on one target Endpoint : GET /api/admin/feed/labels?targetType={type}&targetId={id} · Access : 🛡️ Admin Success Response JSON Sample { "success": true, "httpStatus": "OK", "message": "Labels", "action_time": "2026-09-18T10:30:45", "data": { "targetType": "POST", "targetId": "4f2a77e1-…", "active": ["sensitive_media"], "history": [ { "id": 91, "label": "sensitive_media", "source": "MANUAL", "created_by": "…", "created_at": "2026-09-18T09:00:00Z", "expires_at": "2026-09-21T09:00:00Z", "removed_at": null } ] } } active is what is in force now; history includes removed and expired labels, so a decision can be explained later. source is MANUAL , RULE , REPORT_THRESHOLD or MODEL . Interest mapping Interests are the shared language between social, marketplace and events: one person has one interest profile, and a like on a post can move what they see in the shop. For that to work, every product category, event category and popular hashtag must be mapped to interests . ⚠️ This mapping is not finished. Use B12 to see what is still missing. Until a category is mapped, its items reach people only through follows, trending and fallbacks — not through interests. B11. The interest list and all mappings Endpoint : GET /api/admin/feed/interests · Access : 🛡️ Admin { "success": true, "httpStatus": "OK", "message": "Interest mappings", "action_time": "2026-09-18T10:30:45", "data": { "interests": [ { "id": "…", "name": "Fashion" } ], "productCategories": [ { "key": "b81d9a34-…", "name": "Sneakers", "interestIds": ["…"] } ], "eventCategories": [ { "key": "…", "name": "Live music", "interestIds": ["…"] } ], "hashtags": [ { "key": "mitumba", "name": "#mitumba", "interestIds": ["…"] } ] } } For a hashtag, key is the tag without the # . B12. What still needs mapping Endpoint : GET /api/admin/feed/interests/unmapped · Access : 🛡️ Admin { "success": true, "httpStatus": "OK", "message": "Still to map", "action_time": "2026-09-18T10:30:45", "data": { "productCategories": [ { "id": "…", "name": "Sneakers" } ], "eventCategories": [ { "id": "…", "name": "Workshops" } ], "hashtags": [ { "hashtag": "mitumba", "posts": 812 } ] } } A product category counts as mapped when a parent category is mapped. Hashtags listed are the most used unmapped tags on public posts of the last 30 days — the ones worth mapping first. B13–B15. Map a category or hashtag Endpoints : PUT /api/admin/feed/interests/product-categories/{categoryId} · /event-categories/{categoryId} · /hashtags/{hashtag} · Access : 🛡️ Admin Request JSON Sample { "interestIds": ["a1b2c3d4-…", "e5f6a7b8-…"] } Parameter Type Required Description Validation interestIds array of UUID Yes Replaces the whole mapping for that key. An empty array removes the mapping at most 5 ; every id must exist, else 404 Unknown interest id in […] For /hashtags/{hashtag} , pass the tag with or without # — it is normalised. A value that is not a usable tag gives 404 Not a hashtag: … . An unknown category id gives 404 … not found: {id} . Backfills A backfill republishes data that already exists into the feed's event log — used when a new field is added, after an incident, or when a topic is rebuilt from scratch. Existing rows are read and re-sent; nothing is modified . B16. Start a backfill Endpoint : POST /api/admin/feed/backfills · Access : 🛡️ Super admin Request JSON Sample { "aggregate": "product" } Parameter Type Required Description Validation aggregate string Yes post , follow , block , product , shop , event , profile , order , wishlist , or all else 400 Unknown aggregate '…' Only one run per aggregate at a time. Asking again while one is pending or running returns that existing run instead of starting a second. B17. Recent runs Endpoint : GET /api/admin/feed/backfills · Access : 🛡️ Super admin { "success": true, "httpStatus": "OK", "message": "Backfill runs", "action_time": "2026-09-18T10:30:45", "data": [ { "id": 7, "aggregate": "product", "status": "RUNNING", "lastKey": "8c31a0d2-…", "keysDone": 18400, "keysFailed": 0, "requestedBy": "…", "createdAt": "2026-09-18T10:00:00Z", "startedAt": "2026-09-18T10:00:02Z", "finishedAt": null, "error": null } ] } Field Description status PENDING , RUNNING , DONE , CANCELLED , FAILED lastKey Where it has reached — a cancelled or failed run resumes from here rather than starting over keysDone / keysFailed Progress error Why it failed, when it did B18. Cancel a run Endpoint : POST /api/admin/feed/backfills/{runId}/cancel · Access : 🛡️ Super admin Stops the run at its current key. 404 if that run id does not exist. Related documents Doc What it covers 08_AMENDED_ENDPOINTS.md Existing endpoints that changed, and the old endpoints being deleted 07_FEED_ENDPOINTS_GUIDE.md The app team's walkthrough: paging, the bubble, failure behaviour, switch checklist 05_INTERACTIONS_CLIENT_GUIDE.md Exact definition of every interaction the app sends 06_RECOMMENDATION_DEVELOPER_GUIDE.md For the AI developer: topics, and the lists the feed reads back 01_ARCHITECTURE.md The design behind all of it