# 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`](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](#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: ```json { "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) ```json { "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 ```json { "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 1. **Stop using `clips.length < limit` as the end-of-feed test.** Use `hasMore`. 2. **Honour `visibility`.** `INTERSTITIAL` clips must not autoplay behind no cover. 3. 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 ```json { "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: ```bash 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`](09_NEW_ENDPOINTS.md)	Every new endpoint and new controller
[`07_FEED_ENDPOINTS_GUIDE.md`](07_FEED_ENDPOINTS_GUIDE.md)	The app team's walkthrough of the new feed screens
[`05_INTERACTIONS_CLIENT_GUIDE.md`](05_INTERACTIONS_CLIENT_GUIDE.md)	What the app must report back, and exact action definitions
[`01_ARCHITECTURE.md`](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`](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](#part-a--app-facing)	Android, iOS, web	`HomeFeedController`, `ReelsFeedController`, `MarketFeedController`, `EventsFeedController`, `FeedListsController`, `InteractionController`
🅱️	[Part B — Admin & operations](#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. ```json { "success": true, "httpStatus": "OK", "message": "Home feed", "action_time": "2026-09-18T10:30:45", "data": { } } ``` ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```json { "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`](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`](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 ```json { "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 ```json { "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** ```json { "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** ```json { "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** ```json { "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** ```json { "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 ```json { "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** ```json { "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** ```json { "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 ```json { "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 ```json { "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** ```json { "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** ```json { "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 ```json { "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`](08_AMENDED_ENDPOINTS.md)	Existing endpoints that changed, and the old endpoints being deleted
[`07_FEED_ENDPOINTS_GUIDE.md`](07_FEED_ENDPOINTS_GUIDE.md)	The app team's walkthrough: paging, the bubble, failure behaviour, switch checklist
[`05_INTERACTIONS_CLIENT_GUIDE.md`](05_INTERACTIONS_CLIENT_GUIDE.md)	Exact definition of every interaction the app sends
[`06_RECOMMENDATION_DEVELOPER_GUIDE.md`](06_RECOMMENDATION_DEVELOPER_GUIDE.md)	For the AI developer: topics, and the lists the feed reads back
[`01_ARCHITECTURE.md`](01_ARCHITECTURE.md)	The design behind all of it