Mobile Posts — Integration Guide

For the mobile development. Everything needed to create, edit, read, list, like, and comment on posts. No backend changes needed on your side.

Access control: the private-profile gate (per docs/private-profile-implementation.md) gates every post by its author's profile-privacy state. Restricted profiles return 403 on follower/following lists, and posts by private authors return 404 to non-followers. Saved-list entries by an author who later flips private come back as shells with isUnavailable: true rather than dropping. Per-post visibility (Everyone / Friends) is deferred to a future sprint — see docs/post-visibility-implementation.md.

• API base URL (local): http://localhost:3001
• All requests are JSON. Send Content-Type: application/json.
• Send X-Client-Type: mobile on every request.
• Auth: Authorization: Bearer <accessToken> on every endpoint below (except the S3 PUT for media upload).

What's new

• 2026-09-10 — No client impact: the share link's landing page moved from Cloudflare Pages to Firebase Hosting. Share URLs, the ?ref= code and everything in §18 are unchanged; only the "Domain + TLS" row in §18.7 says a different vendor.
• 2026-09-09 — Share URLs changed shape: POST /api/posts/:id/share now returns https://letsclustr.com/posts/<id>?ref=<code>. The /p/<id> form documented here before was wrong — it was never served by anything and no longer exists. The link now really does open the app (or a download page) once the app claims the domain; profiles are shareable too via GET /api/users/:username/share. Full contract: mobile-deep-links-guide.md.
• 2026-09-07 — The topic picker is now the 9 interest categories, not the ~1130 fine-grained topics. Nothing changes in the request: still topicSlugs, still 1–2, still slugs from GET /api/users/topics — that call just returns 9 rows now ("sports-fitness", "academics-learning", …). Don't hardcode the list; fine-grained topics come back later on semantic matching and only the option list will change.
• 2026-09-01 — topicSlugs is now optional on ANYTHING posts — leave it out or send [], both work. The other four post kinds still need 1–2 topics. Also corrected here: the field table said 1–10 topics; the real limit is 2, and has been since the topic taxonomy shipped.

---

Short version — just the API calls

0. GET    /api/posts/types                → post-type catalog (summary: 5 kinds)
   GET    /api/posts/types/:slug          → full detail for one kind (fields + CTA + defaults)
   GET    /api/users/topics                → interest/topic catalog
1. POST   /api/media/presign               → { uploadUrl, publicUrl }   (per file)
   PUT    <uploadUrl>                      (file bytes, direct to S3)
2. POST   /api/posts                       → create post
3. GET    /api/posts/:id                   → single post
4. GET    /api/posts/me                    → current user's posts
5. GET    /api/posts/user/:username        → another user's posts
6. GET    /api/posts?type=&topicSlug=...   → filtered list
7. GET    /api/feed                        → personalized feed
8. PATCH  /api/posts/:id                   → edit a post
9. DELETE /api/posts/:id                   → delete a post
10. PUT    /api/posts/:id/like             → set like state (idempotent, body: {liked})
11. PUT    /api/posts/:id/save             → set save state (idempotent, body: {saved})
12. GET    /api/posts/saved                → viewer's saved posts (private bookmarks)
13. POST   /api/posts/:id/repost           → one-tap repost (empty body)
14. DELETE /api/posts/:id/repost           → undo repost
15. GET    /api/posts/:id/reposts          → list of repost rows
16. POST   /api/posts/:id/share            → record share + return tracked URL
17. GET    /api/posts/:id/share/preview    → share-sheet prefill (title/desc/image)
18. GET    /api/posts/:id/comments         → list comments + replies
19. POST   /api/posts/:id/comments         → add comment / reply

All catalogs (/posts/types, /posts/types/:slug, /users/topics) send Cache-Control: public, max-age=3600. Cache them locally for the session.

---

1 — Post types (drive your form)

Two-call split:

• GET /api/posts/types → summary list. Drives the type picker.
• GET /api/posts/types/:slug → full detail for one kind. Drives the form on selection (fields, CTA, request-prompt defaults).

1.1 — Summary list

{
  "success": true,
  "data": [
    {
      "kind": "FIND_TEAMMATES",
      "slug": "find-teammates",
      "name": "Find Teammates",
      "description": "Build a team or find partners for something you want to do",
      "icon": "users",
      "order": 1,
    },
    {
      "kind": "INVITE_PEOPLE",
      "slug": "invite-people",
      "name": "Invite People",
      "description": "Get others to join something you're hosting",
      "icon": "mail",
      "order": 2,
    },
    {
      "kind": "START_SOMETHING",
      "slug": "start-something",
      "order": 3 /* ... */,
    },
    {
      "kind": "SHARE_OPPORTUNITY",
      "slug": "share-opportunity",
      "order": 4 /* ... */,
    },
    { "kind": "ANYTHING", "slug": "anything", "order": 5 /* ... */ },
  ],
}

Use the catalog as the source of truth. Don't hardcode the kind list — it WILL change. Render the picker from data[] ordered by order.

1.2 — Per-kind detail (GET /api/posts/types/:slug)

Call this on kind selection (or pre-warm all five on cold-start — they're 1h cached). Returns fields, CTA, request-prompt defaults:

{
  "success": true,
  "data": {
    "kind": "FIND_TEAMMATES",
    "slug": "find-teammates",
    "name": "Find Teammates",
    "description": "Build a team or find partners for something you want to do",
    "icon": "users",
    "order": 1,
    "fields": {
      "required": [
        "title",
        "content",
        "topicSlugs",
        "eventAt",
        "locationMode",
        "deadlineAt",
      ],
      "optional": ["media", "location", "locationPlace", "link"],
    },
    "cta": {
      "enabled": true,
      "verb": "join",
      "buttonLabel": "Request to Join",
      "pendingLabel": "Request Sent",
      "acceptedLabel": "Joined",
      "rejectedLabel": "Request Declined",
      "authorLabel": "View Responses",
    },
    "defaultRequestPrompt": "Why are you a good fit?",
    "defaultRequestPromptDescription": "Pick what best describes you so the creator can review responses quickly.",
    "defaultRequestOptions": ["I have experience", "I'm interested", "..."],
  },
}

Render only fields in required ∪ optional. Mark required ones. 404 on unknown slug.

Per-kind field sets:

slug	required	optional
find-teammates	title, content, topicSlugs, eventAt, locationMode, deadlineAt	media, location, locationPlace, link
invite-people	title, content, topicSlugs, eventAt, locationMode, deadlineAt	media, location, locationPlace, link
start-something	title, content, topicSlugs, locationMode	media, location, locationPlace, link
share-opportunity	title, content, topicSlugs, location, eventAt	media, link
anything	(none)	content, media, location, topicSlugs

The 3 CTA kinds carry an Online / In-person toggle (locationMode). It's required, but location / locationPlace / link show as optional above because which one is required depends on the toggle — the server enforces the real rule (see §1.3). This mirrors anything, whose required list is empty while the server still requires content-or-media (§4.5).

Field meanings:

field name	type	sent as
title	string ≤120	body.title
content	string ≤2000	body.content (description body)
topicSlugs	string[] (1–2)	body.topicSlugs — category slugs from /api/users/topics (§2). Required on the 4 CTA/event kinds; optional on anything (§4.5)
media	object[] (≤10)	body.media — see §3
location	string ≤200	body.location — display string (in-person only)
locationMode	enum	body.locationMode — ONLINE | IN_PERSON on the 3 CTA kinds (§1.3)
locationPlace	object	body.locationPlace — structured Places blob incl. city (in-person, §1.3). Returned only by GET /api/posts/:id
eventAt	ISO 8601 datetime	body.eventAt
deadlineAt	ISO 8601 datetime	body.deadlineAt — required on find-teammates / invite-people
link	URL	body.link — meeting URL (online) or RSVP/details URL

eventAt / deadlineAt are one instant — not a date plus a time. Merge the date picker and the time picker in device-local time, then send a single ISO string:

const at = new Date(2026, 7, 30, 1, 0); // Aug 30, 1:00 am device-local
eventAt: at.toISOString(); // "2026-08-29T19:30:00.000Z"

Sending only the date value gives you midnight — 2026-08-29T18:30:00.000Z is Aug 30 00:00 IST — and the time the user picked is gone.

There is no time field, and unknown keys are silently dropped: a body carrying "eventAt": "...T18:30:00.000Z", "time": "1:00 am" returns 201 with the event stored at midnight. No validation error will tell you.

Both columns are stored and returned as UTC with no timezone attached — every client renders them in its own device timezone. A same-region audience sees the time the author meant; a viewer in another timezone sees it shifted.

1.3 — Online / In-person toggle (the 3 CTA kinds only)

FIND_TEAMMATES, INVITE_PEOPLE, START_SOMETHING each require a locationMode toggle with exactly two choices:

• ONLINE (virtual) → show a link field. link is required; location / locationPlace must be absent.
• IN_PERSON → show a location field. location is required; link is optional (some events add an RSVP/details URL), and locationPlace is optional-but-expected.

link is valid in both modes. The two modes are mutually exclusive — there is no hybrid.

Location data (in-person). The client picks a place via the Google Places API and sends both a human-readable location string (for display) and a structured locationPlace blob (for the detail-page map pin + future "events near me"):

"location": "Ocean Beach, San Francisco, CA",
"locationPlace": {
  "placeId": "ChIJ...",           // Google Place ID
  "name": "Ocean Beach",          // optional
  "formattedAddress": "Ocean Beach, San Francisco, CA 94121",
  "lat": 37.7594,
  "lng": -122.5107,
  "city": "San Francisco",        // SEND THIS — it's what the feed renders
  "region": "California",         // optional
  "country": "United States"      // optional
}

Always send city. Take it from the Place Details address_components (locality, falling back to postal_town / administrative_area_level_2). It is the only location the feed shows — see the precision rule below. It's optional in the schema so older builds keep working, but without it the feed falls back to whatever free text you put in location, which may be a street address.

Validation errors (HTTP 400) when the invariant is broken:

you sent	error
ONLINE with no link	link is required for online posts
ONLINE with a location	location is not allowed on online posts
ONLINE with a locationPlace	locationPlace is not allowed on online posts
IN_PERSON with no location	location is required for in-person posts

locationMode values CITY / SCHOOL / HYBRID are legacy — old START_SOMETHING rows may still carry them and render fine, but the composer only ever sends ONLINE / IN_PERSON. The response locationPlace is null on online posts and on any legacy/pre-toggle row.

Location precision differs by endpoint. This is a privacy rule, not a payload optimisation — a scrollable feed must not publish the exact coordinates of a kid's meetup:

Surface	location	locationPlace
GET /api/posts, /me, /saved, /user/:userName, GET /api/feed	locality only — "San Francisco"	absent
GET /api/posts/:id	exact, as the author entered it	full blob incl. lat/lng

The coarse value is locationPlace.city when you sent one, otherwise the author's typed location. It applies to the author's own posts too — the author sees exact values by opening the post. locationMode is present on every surface, so the Online / In-person badge still renders on feed cards.

Practically: feed cards have no map pin and no maps deep link (there are no coordinates to build one from) — render the locality as plain text. Fetch the post detail before offering "open in Maps".

Viewer render on the detail page — tap to open Maps. A viewer sees post.location as tappable text; the tap opens the device Maps app. Build the deep link client-side from the fields you already have — the server does not ship a maps URL (it can't pick the native app per-platform):

• Has locationPlace (precise pin): https://www.google.com/maps/search/?api=1&query=<lat>,<lng>&query_place_id=<placeId> → opens the exact place. iOS-native alternative: https://maps.apple.com/?ll=<lat>,<lng>&q=<name>. RN: Linking.openURL(...), or geo:<lat>,<lng>?q=<lat>,<lng>(<name>) on Android.
• No locationPlace (author typed free text): https://www.google.com/maps/search/?api=1&query=<encodeURIComponent(post.location)> → text search fallback.

For online posts there's no location — render post.link as the joinable meeting URL instead.

---

2 — Topics dropdown (interest tags)

GET /api/users/topics — the 9 interest categories. Cached 1h; fetch once per session and reuse. Same response shape as everywhere else.

Onboarding's interest step is a different list — ?representative=1, ~86 fine-grained topics. Don't share one cached list between the two screens. See mobile-topics-interests-guide.md.

{
  "success": true,
  "data": [
    {
      "id": "tpc_xxx",
      "slug": "sports-fitness",
      "name": "Sports & Fitness",
      "category": "Sports & Fitness",
      "icon": null,
    },
    {
      "id": "tpc_yyy",
      "slug": "arts-creativity",
      "name": "Arts & Creativity",
      "category": "Arts & Creativity",
      "icon": null,
    },
    // ... 9 in total
  ],
}

Send the chosen slug values back as topicSlugs: ["sports-fitness","arts-creativity"] — the slug, never the display name. Unknown slugs are silently dropped server-side, so a create with only bad slugs succeeds with no topics; validate against this list client-side.

---

3 — Media flow

Same presign flow as onboarding. Two steps per file:

3.1 — Presign

POST /api/media/presign
Content-Type: application/json
Authorization: Bearer <accessToken>

{
  "files": [
    { "filename": "photo1.jpg", "contentType": "image/jpeg", "size": 245678 }
  ]
}

Posts are image-only (image/jpeg, image/png, image/webp, max 10 MB; image/heic/image/heif iOS photos, max 15 MB). Video and gif are rejected. size (exact byte length) is required — the server caps it and pins it as the signed Content-Length.

Response:

{
  "success": true,
  "data": {
    "files": [
      {
        "uploadUrl": "https://s3.../signed?...",
        "publicUrl": "https://s3.../uploads/abc.jpg",
      },
    ],
  },
}

3.2 — PUT to S3

PUT <uploadUrl>
Content-Type: image/jpeg    ← MUST match what you sent to /presign
Content-Length: 245678      ← MUST match the presigned size (exact)

<binary bytes>

No auth headers — the signed URL is the credential. Storage rejects a body whose length isn't exactly the presigned size (403).

3.3 — Include media inline on create

Pass each uploaded file in the media[] array of the create body. Server creates the Media rows polymorphically (ownerType=post) in the same request.

"media": [
  {
    "type": "image",          // image ONLY (video/gif rejected on posts)
    "url": "https://s3.../uploads/abc.jpg",
    "thumbnailUrl": "https://...",   // optional
    "width": 1080,            // optional
    "height": 1920,           // optional
    "size": 245678,           // optional, bytes
    "altText": "Team photo"   // optional
  }
]

Max 10 media per post. Media is set at create time only — editing a post cannot add media. To remove existing items, PATCH with removeMediaIds (see §6).

---

4 — Creating a post

Same endpoint for every kind. The type field discriminates. Server validates per-kind required set.

4.1 — Find Teammates

POST /api/posts
{
  "type": "FIND_TEAMMATES",
  "title": "Looking for a 4th for our hackathon team",
  "content": "Building a flashcard app. Need a designer or another dev.",
  "topicSlugs": ["technology-innovation"],
  "eventAt": "2026-06-12T10:00:00Z",        // event date
  "deadlineAt": "2026-06-10T23:59:59Z",     // deadline
  "locationMode": "IN_PERSON",              // required — ONLINE | IN_PERSON (§1.3)
  "location": "San Francisco",              // required when IN_PERSON
  "locationPlace": {                         // structured Places blob (in-person)
    "placeId": "ChIJ...", "formattedAddress": "San Francisco, CA",
    "lat": 37.7749, "lng": -122.4194,
    "city": "San Francisco"                  // what the feed renders (§1.3)
  },
  "media": [ { "type": "image", "url": "..." } ]
}

Online variant: "locationMode": "ONLINE", "link": "https://meet.example/x" and no location / locationPlace. See §1.3 for the full rule.

4.2 — Invite People

{
  "type": "INVITE_PEOPLE",
  "title": "Beach cleanup this Saturday",
  "content": "Bring gloves. We'll provide bags.",
  "topicSlugs": ["business-leadership"],
  "eventAt": "2026-05-25T09:00:00Z",
  "deadlineAt": "2026-06-10T23:59:59Z", // deadline
  "locationMode": "IN_PERSON", // required — ONLINE | IN_PERSON (§1.3)
  "location": "Ocean Beach, San Francisco", // required when IN_PERSON
  "locationPlace": {
    "placeId": "ChIJ...",
    "formattedAddress": "Ocean Beach, San Francisco, CA",
    "lat": 37.7594,
    "lng": -122.5107,
    "city": "San Francisco", // what the feed renders (§1.3)
  },
  "link": "https://rsvp.example/beach", // optional — link allowed in-person
}

4.3 — Start Something New

{
  "type": "START_SOMETHING",
  "title": "Starting a robotics club",
  "content": "Anyone interested in meeting weekly to build robots?",
  "topicSlugs": ["technology-innovation", "competitive-activities"],
  "locationMode": "ONLINE", // required — ONLINE | IN_PERSON (§1.3)
  "link": "https://discord.gg/robotics", // required when ONLINE; no location
}

In-person variant: "locationMode": "IN_PERSON" with location (+ locationPlace) instead of link.

4.4 — Share an Opportunity

{
  "type": "SHARE_OPPORTUNITY",
  "title": "STEM scholarship — applications open",
  "content": "Open to grades 9–12. $5000 award.",
  "topicSlugs": ["academics-learning"],
  "location": "Online",
  "eventAt": "2026-07-01T23:59:59Z", // deadline / event time
  "link": "https://example.org/apply", // optional external URL
}

4.5 — Post Anything

{
  "type": "ANYTHING",
  "content": "Just had the best burrito of my life.",
  "media": [{ "type": "image", "url": "..." }],
}

type is the only structurally required field. topicSlugs is optional on this kind only — omit the key, or send []; both mean the same thing and the server derives the feed signal itself from the text. Send 1–2 slugs when the author picked topics and those win over the derived ones. Every other kind still rejects a create without topicSlugs (400).

The one rule the server does enforce: content or media — a post with neither is a 400 on content ("Add some text or at least one photo/video").

4.6 — Response shape (all kinds)

This is the detail shape (create / update / GET /api/posts/:id). List and feed responses are identical except for location: location holds the locality only and locationPlace is absent — see §1.3.

{
  "success": true,
  "data": {
    "id": "pst_xxx",
    "type": "FIND_TEAMMATES",
    "title": "...",
    "content": "...",
    "location": "...", // exact here; locality-only on list/feed (§1.3)
    "locationMode": null,
    "locationPlace": null, // detail only — never present on list/feed
    "eventAt": "2026-06-12T10:00:00Z",
    "deadlineAt": "2026-06-10T23:59:59Z",
    "link": null,
    "details": null,
    "authorId": "usr_yyy",
    "isHidden": false,
    "createdAt": "2026-05-19T12:00:00Z",
    "updatedAt": "2026-05-19T12:00:00Z",
    "author": {
      "id": "usr_yyy",
      "username": "alice",
      "profile": { "displayName": "Alice", "avatarUrl": "..." },
    },
    "topics": [
      { "id": "tpc_xxx", "slug": "coding", "name": "Coding", "icon": "code" },
    ],
    "media": [
      {
        "id": "med_zzz",
        "type": "image",
        "url": "...",
        "thumbnailUrl": "...",
        "width": 1080,
        "height": 1920,
        "altText": null,
      },
    ],
    "_count": { "likes": 0, "comments": 0 },
    "isLiked": false,
  },
}

The response shape is identical across all kinds. Kind-specific columns are null when not applicable. This means your detail screen / list cell can use one render path with conditional sub-views by type.

---

5 — Reading posts

5.1 — Single post

GET /api/posts/:id

Returns the same shape as create. Includes top-level comments[] (just the first batch — paginate via §11 for more).

5.2 — Current user's posts

GET /api/posts/me?limit=20&cursor=<base64>

5.3 — Another user's posts

GET /api/posts/user/:username?limit=20&cursor=<base64>

404 if username doesn't exist.

5.4 — List with filters

GET /api/posts?type=FIND_TEAMMATES&topicSlug=coding&upcomingOnly=true&limit=20

Query params (all optional, all combine with AND):

param	meaning
type	FIND_TEAMMATES/INVITE_PEOPLE/START_SOMETHING/SHARE_OPPORTUNITY/ANYTHING
topicSlug	only posts tagged with this topic
authorUsername	only posts by this user
upcomingOnly	"true" → require eventAt >= now()
cursor	from previous response's nextCursor
limit	default 20, max 50

5.5 — Personalized feed

GET /api/feed?limit=20&cursor=<id>

Unchanged from before. Blends follows + interests + trending. Items have the same shape as list endpoints plus score, pool, mode.

5.6 — List response shape

{
  "success": true,
  "data": {
    "items": [
      /* array of full post objects, same shape as §4.6 */
    ],
    "nextCursor": "eyJj...", // or null if no more pages
  },
}

Pass nextCursor back as ?cursor= to fetch the next page. Stop when null.

---

6 — Updating a post

PATCH /api/posts/:id

All fields optional — omit a field to leave it unchanged. type is immutable — cannot change after create.

6.1 — Per-type field validation

Edits are validated against the post's type using the same catalog that drives your create form (GET /api/posts/types/:slug, fields.required / fields.optional):

the field is…	value sent	null sent
required for the type	applied	400 — cannot be cleared
optional for the type	applied	applied — clears the field
not in the type's form	400 — not supported	silently ignored

The null-is-ignored rule means you can PATCH your whole flat form state — sending null for every field the type's form doesn't render — without triggering errors. A 400 only fires when you send an actual value for a field the type doesn't have (e.g. deadlineAt on a START_SOMETHING post), which indicates a client bug.

6.2 — Per-type edit matrix

type	editable, can't clear (null → 400)	editable + clearable (null clears)	rejected if value sent (null ignored)
FIND_TEAMMATES	title, content, topicSlugs, eventAt, locationMode, deadlineAt	location, locationPlace, link	—
INVITE_PEOPLE	title, content, topicSlugs, eventAt, locationMode, deadlineAt	location, locationPlace, link	-
START_SOMETHING	title, content, topicSlugs, locationMode	location, locationPlace, link	eventAt, deadlineAt
SHARE_OPPORTUNITY	title, content, topicSlugs, location, eventAt	link	locationMode, deadlineAt
ANYTHING	topicSlugs, content	location	title, locationMode, eventAt, deadlineAt, link
REPOST	—	—	all typed fields (reposts aren't editable)

Rules that apply to every type:

• topicSlugs REPLACES the topic set (never merged, cannot be null).
• Media cannot be added on edit (media is create-only). To remove existing media, pass removeMediaIds — an array of media ids (from the post's media[]). Ids that don't belong to this post are ignored. Removed rows are deleted along with their storage blobs.
• requestPrompt / requestPromptDescription / requestOptions — CTA-enabled kinds only (FIND_TEAMMATES, INVITE_PEOPLE, START_SOMETHING); frozen with 409 once the first request exists (§15.12). On non-CTA kinds a value → 400, null → ignored.
• Online / in-person invariant applies on edit too (§1.3). The server checks the merged result: e.g. flipping locationMode to ONLINE while a location is still set → 400 (location is not allowed on online posts). When flipping modes, send the new field and clear the other (location: null when going online, or link: null + location: "..." when going in-person). Only fires for ONLINE / IN_PERSON; legacy CITY/SCHOOL/HYBRID rows are unconstrained.
• Time-bound posts freeze after the event. Once eventAt has passed, any edit returns 409 ("Post can no longer be edited after its event date"). Posts without eventAt never lock. Hide/disable the edit action when the event date is in the past.

6.3 — Examples

Edit a FIND_TEAMMATES post — move the event, move the deadline, remove a photo:

PATCH /api/posts/pst_xxx
{
  "title": "Updated title",
  "content": "Updated description",
  "topicSlugs": ["coding", "design", "art"],
  "eventAt": "2026-06-15T10:00:00Z",   // required for this type — value OK, null would 400
  "deadlineAt": "2026-06-14T10:00:00Z", // required for this type — value OK, null would 400
  "removeMediaIds": ["med_abc123"]
}

Edit a START_SOMETHING post — flat form dump, nulls for fields the form doesn't render are fine:

PATCH /api/posts/pst_yyy
{
  "title": "Robotics club v2",
  "content": "Now meeting twice a week.",
  "topicSlugs": ["robotics"],
  "locationMode": "ONLINE",
  "location": null,        // optional for this type — clears it
  "eventAt": null,         // not in this type — ignored, no error
  "deadlineAt": null,      // not in this type — ignored, no error
  "link": null             // optional for this type — clears it
}

Sending "deadlineAt": "2026-08-01T10:00:00Z" (a real value) on that same START_SOMETHING post → 400 "deadlineAt is not supported on START_SOMETHING posts".

6.4 — Errors

code	meaning
400	Value for a field the type doesn't have, or null for a required-for-type field
403	Not the post author
404	Post not found (or author private + viewer not approved)
409	Event date has passed, or request prompt frozen after first request (§15.12)

---

7 — Deleting a post

DELETE /api/posts/:id

Hard-delete. Cascades comments, likes, media (rows + storage blobs), mentions. 403 if not author. 404 if not found.

---

8 — Like / unlike

PUT /api/posts/:id/like
Content-Type: application/json

{ "liked": true }       // or false to unlike

Idempotent. {liked: true} is a no-op if already liked; {liked: false} is a no-op if not liked. The client sends the desired state directly, so the server never has to reconstruct intent from arrival order.

Response:

{
  "success": true,
  "data": {
    "liked": true, // echoes the requested state
    "updatedAt": "2026-05-22T07:35:40.451Z",
  },
}

isLiked on the post object reflects the current user's state. _count.likes on list / detail responses is the authoritative count — trust it on refetch / hydration / pagination.

GET /api/posts/:id/likes returns the liker list, sorted with the viewer's followers/following first.

8.1 — Optimistic UI (mandatory pattern)

Do not show a spinner on the like button. Apply the change locally on tap and reconcile with the server in the background.

1. On tap — flip isLiked and bump _count.likes by +1 (like) or -1 (unlike) immediately in the client store. Record the new value as the desired state for this post.
2. Fire PUT /api/posts/:id/like with { liked: <desired> } in the background. No await on the UI thread.
3. On HTTP error — roll back the local state and surface a toast ("Couldn't update — tap to retry"). Do not block other interactions.
4. On feed refetch / detail screen open — trust the server's _count.likes and isLiked as the source of truth; overwrite local state.

8.2 — Race conditions (rapid tap)

PUT is idempotent and carries the desired state in the body, so the server no longer guesses intent from arrival order. But rapid taps can still produce out-of-order responses on the wire, so:

• Serialize per post — keep at most one in-flight like mutation per postId. Cancel the previous one before issuing a new one. With TanStack Query: queryClient.cancelQueries({ queryKey: ["post-like", postId] }) inside onMutate.
• Track desired state — store the user's latest intended liked value client-side. After each response, only apply it if its updatedAt is strictly newer than the last applied response for that post. Discard older updatedAt responses — they reflect an obsolete tap.
• Idempotent retry on failure — safe to re-send the same { liked: <desired> } body. PUT is idempotent, so retrying never double-counts.

The endpoint is also rate-limited (per-user, 30 calls per 10s). Don't re-fire on every render — debounce taps that happen faster than a human can tap.

---

9 — Comments

9.1 — List

GET /api/posts/:id/comments?limit=20&cursor=<commentId>

Returns top-level comments, ordered newest first. Single-level nesting (Instagram-style): each top-level comment carries a flat replies[] array — replies are never themselves nested. Auth required (Bearer token) — the response's per-comment isLiked is computed for the calling user.

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "cmt_xxx",
        "content": "...",
        "authorId": "...",
        "postId": "...",
        "parentId": null,
        "createdAt": "...",
        "author": {
          /* id, username, profile */
        },
        "likeCount": 3,
        "isLiked": false, // viewer's like state on this comment
        "replies": [
          {
            /* same shape (incl. likeCount + isLiked),
               parentId = the top-level comment id.
               replies[] is NOT present on these (flat — one level only). */
          },
        ],
      },
    ],
    "nextCursor": "cmt_yyy",
    "total": 42,
  },
}

9.2 — Create comment / reply

POST /api/posts/:id/comments
{
  "content": "@bob Sounds great!",   // client owns the text, incl. any @handle
  "parentId": "cmt_xxx"              // omit for top-level
}

Single-level nesting + client-owned composer. parentId may point at a top-level comment or at a reply — the server flattens threading to one level either way (parentId collapses to the root comment) and records the reply relationship separately in replyToUserId.

• The server stores content verbatim — it never injects or re-adds an @handle. When the user taps "Reply", prefill @<handle> yourself; the user may edit or delete it.
• Reply notification is driven by the relationship, not the text: the replied-to author always gets "replied to your comment" (type: comment), even if the @handle was deleted. Skipped only on a self-reply.
• Other @mentions in the text notify those users (type: mention), deduped against the reply/comment recipient — one notification per person per comment.
• A top-level comment notifies the post author ("commented on your post"), with the same dedup.

The response echoes the stored content, parentId (root), and replyToUserId. Render @handle tokens using the mention offsets (see §10) for tap-to-profile.

9.3 — Like a comment

PUT /api/posts/:postId/comments/:commentId/like
{ "liked": true }     // or false to unlike

Response — like state after the call:

{
  "success": true,
  "data": {
    "liked": true,
    "likeCount": 4,
    "updatedAt": "2026-06-30T07:35:40.451Z",
  },
}

Boolean like, one per user per comment (mirrors the post like). Works on top-level comments and replies alike. Behaviors:

• Idempotent — repeating the same state is a no-op (liked:true when already liked stays likeCount unchanged). Safe to retry / double-tap.
• Self-like allowed — you can like your own comment (no notification fires).
• Notification — the comment author is notified only on the first unliked→liked transition (type: "like", data.entityType: "comment"). Unliking and re-liking does not re-notify within the same row lifetime.
• 404 when the comment doesn't exist, isn't in :postId, or the post isn't visible to you.
• Rate-limited 30 / 10s per user (429, no body).

Optimistic UI: flip isLiked + adjust likeCount locally on tap, fire the PUT in the background, reconcile from likeCount/updatedAt on response, roll back on HTTP error. Same pattern as the post like.

9.4 — Delete comment

DELETE /api/posts/:postId/comments/:commentId

403 if not comment author. Cascades replies (and their likes).

---

10 — Mentions (@username)

Server auto-detects @username in post + comment content. Mentioned users get a notification. Behavior is identical to existing flows — no extra work needed.

---

11 — Pagination cursor

All paginated list endpoints use base64url-encoded (createdAt, id) cursors. Treat the value as opaque. Pass it back via ?cursor=.... The server returns nextCursor: null on the final page.

Comment lists use the comment ID as the cursor (simpler than time-based for comment threads).

---

12 — Error responses

Validation errors → HTTP 400 with details:

{
  "success": false,
  "error": "Validation error",
  "details": [
    {
      "code": "invalid_type",
      "path": ["eventAt"],
      "message": "Required",
    },
  ],
}

Other errors:

code	meaning
401	Missing or invalid Authorization header
403	Not the author (edit / delete), OR target profile private + viewer not approved
404	Post / user / comment not found, OR author profile is private + viewer not approved
429	Per-route rate limit (catalogs use a 60s/30req bucket)
500	Server error — capture request_id if present

Private-profile gating: when the author of a post has set profile.isPrivate=true and the viewer is not an approved follower, every post-scoped endpoint (GET /api/posts/:id, all sub-resources, all write routes including like/save/comment) returns 404 — the post "does not exist" for the viewer (Instagram behavior). Profile-list endpoints (/api/follows/:userId/{followers,following,friends}, /api/posts/user/:userName) return 403 with { error: "private_profile" }. See docs/private-profile-implementation.md for the full surface.

---

13 — When the post-type list changes

The list of post kinds is a product decision and may shift. Backend changes:

• Add a kind → server adds enum + catalog entry + validator arm.
• Drop a kind → server removes them.

On mobile, re-fetch /api/posts/types after each app cold-start (the 1h cache makes this cheap), and fetch /api/posts/types/:slug on kind selection (or pre-warm all five). Don't ship a hardcoded list. The catalog drives everything — picker labels, form fields, required-vs-optional, CTA labels, request-prompt defaults.

---

14 — Open questions

already on the radar:

• Per-post visibility (followers-only, friends-only, private) — not yet implemented; every post is public to authenticated users right now.
• Drafts / scheduled posts — not yet implemented.
• Repost / share to chat — not yet implemented.
• Reactions beyond like — only like exists today.

---

15 — Type-specific CTAs & Requests

Three of the five post kinds expose a request CTA:

kind	viewer CTA	author CTA
FIND_TEAMMATES	Request to Join	View Responses
INVITE_PEOPLE	Request to Attend	View Responses
START_SOMETHING	Request to Collaborate	View Responses
SHARE_OPPORTUNITY	(none)	(none)
ANYTHING	(none)	(none)

All CTA labels are server-provided — never hardcode them. They come from the per-kind detail (GET /api/posts/types/:slug) and are also inlined on every post object as post.cta. The server flips buttonLabel based on viewer state (author / pending / accepted / rejected / fresh).

15.1 — Where CTA + defaults live

GET /api/posts/types/:slug (see §1.2) returns the per-kind cta block and the defaultRequestPrompt / defaultRequestPromptDescription / defaultRequestOptions. The summary list (GET /api/posts/types) does not include these — fetch the detail when the user picks a kind.

Use the defaults as form placeholders when a user is creating a CTA-enabled post. If the author tweaks them, send the overrides on the create body.

15.2 — Authoring custom prompt/options

CTA-enabled create requests accept three optional fields:

POST /api/posts
{
  "type": "FIND_TEAMMATES",
  "title": "Looking for a Debate Partner",
  "content": "Need a 4th for state regionals.",
  "topicSlugs": ["debate"],
  "eventAt": "2026-04-25T10:00:00Z",
  "location": "San Jose, CA",
  "requestPrompt": "Why are you a good fit?",
  "requestPromptDescription": "Pick what best describes you so the creator can review responses quickly.",
  "requestOptions": [
    "I have experience",
    "I'm interested",
    "I'm available on those dates",
    "I'm highly motivated"
  ]
}

• Omit all three → server fills from catalog defaults, sets requestPromptSource = "DEFAULT".
• Provide any of them → requestPromptSource = "AUTHOR".
• Sending any of them on SHARE_OPPORTUNITY / ANYTHING → 400.
• Once the first PostRequest row exists, PATCH /api/posts/:id rejects edits to these three fields with 409 (snapshot integrity for existing responders).

15.3 — Post response additions (every list + detail endpoint)

{
  // ...existing fields...
  "requestPrompt": "Why are you a good fit?",
  "requestPromptDescription": "Pick what best describes you so the creator can review responses quickly.",
  "requestOptions": ["I have experience", "I'm interested", "..."],
  "requestPromptSource": "DEFAULT", // DEFAULT | AUTHOR | AI | null
  "requestState": "OPEN", // OPEN | PAUSED | COMPLETED — author-controlled intake (CTA kinds; OPEN otherwise)
  "cta": {
    "enabled": true,
    "verb": "join",
    "buttonLabel": "Request to Join", // resolved for current viewer + requestState
    "pendingLabel": "Request Sent",
    "acceptedLabel": "Joined",
    "rejectedLabel": "Request Declined",
    "authorLabel": "View Responses",
    "pausedLabel": "Requests Paused", // shown to a fresh viewer when requestState=PAUSED
    "completedLabel": "Closed", // shown to a fresh viewer when requestState=COMPLETED
    "actionable": true, // false → render the pill disabled (no tap target)
  },
  "viewerRequestStatus": null, // PENDING | ACCEPTED | REJECTED | WITHDRAWN | null
  "_count": { "likes": 3, "comments": 5, "requests": 12 },
  //                                     ^^^^^^^^ pending count, author only (0 for others)
}

Mobile render rule for the CTA pill:

• cta.enabled === false → don't render the pill.
• otherwise render cta.buttonLabel — server has already swapped it for the author's "View Responses", a requester's "Request Sent" / "Joined" / "Request Declined", or (for a fresh viewer on a paused/closed post) the "Requests Paused" / "Closed" label.
• cta.actionable === false → render the pill disabled (greyed, no tap). True only when the viewer can actually act — a fresh viewer on an OPEN post, or the author (whose "View Responses" is always tappable).
• Use requestState to render an intake badge on the card (e.g. a "Paused" / "Closed" chip) independent of the viewer's own request status.

15.4 — Submit a request

POST /api/posts/:id/requests
{
  "selectedOptions": ["I'm interested", "I'm available on those dates"],
  "message": "I've competed at state level for two years."  // optional, ≤500
}

• selectedOptions must be a subset of post.requestOptions (server validates per-string; sending an unknown option → 400).
• Idempotent on (postId, requesterId): re-submit after a WITHDRAWN/REJECTED flips the row back to PENDING and refreshes the answers.
• 400 if the post type has no CTA or if you're the post author.
• 409 if you're already ACCEPTED — withdrawing is a no-op at that point.
• 429 if you exceed 100 submissions in a rolling 24h window.

Response payload is the full PostRequest row including the embedded requester summary.

15.5 — Withdraw your request

DELETE /api/posts/:id/requests/me

Sets status = WITHDRAWN (audit trail preserved). Only PENDING rows can be withdrawn — accepted/rejected → 409.

15.6 — Author: view responses (the "View Responses" tap target)

GET /api/posts/:id/requests?status=PENDING&limit=20&cursor=<base64>

Author-only. Returns the request inbox for one post.

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "req_xxx",
        "postId": "pst_yyy",
        "requesterId": "usr_zzz",
        "status": "PENDING",
        "selectedOptions": ["I'm interested", "I'm available on those dates"],
        "message": "I've competed at state level for two years.",
        "respondedAt": null,
        "respondedBy": null,
        "createdAt": "2026-05-19T12:00:00Z",
        "updatedAt": "2026-05-19T12:00:00Z",
        "requester": {
          "id": "usr_zzz",
          "username": "adam",
          "profile": { "displayName": "Adam", "avatarUrl": "..." },
        },
      },
    ],
    "nextCursor": null,
    "counts": { "pending": 12, "accepted": 3, "rejected": 1, "withdrawn": 2 },
  },
}

counts is unfiltered (always returns totals across every status) so you can render tab badges. items honors the status filter.

15.7 — Author: accept / reject

PATCH /api/posts/:id/requests/:reqId
{ "action": "accept" }    // or "reject"

Only PENDING rows can be transitioned. Server emits notification to requester (post_request_accepted / post_request_rejected). No side-effects beyond status change in v1 — no auto chat, no event join.

15.8 — Author: aggregate inbox across all your posts

GET /api/posts/requests/inbox?status=PENDING&limit=20

Same response shape as §15.6 but each row also includes a post summary ({ id, type, title, content, authorId, eventAt, createdAt }) so the list can show "X requested to join Looking for a Debate Partner". Default status filter is PENDING.

15.9 — Requester: my outgoing requests

GET /api/posts/requests/mine?status=PENDING&limit=20

Returns the viewer's requests across every post they've ever requested, with the same post summary embedded. No counts block.

15.10 — Notifications

type	recipient	trigger
post_request	post author	viewer submits or re-submits a request
post_request_accepted	original requester	author accepts
post_request_rejected	original requester	author rejects
post_deleted	original requester	author deletes a post that had pending reqs

All payloads include data.entityType="post", data.entityId=<postId>, data.postType=<PostType>, plus requestId for the request-scoped ones.

15.11 — Error reference

code	meaning
400	CTA disabled / self-request / selectedOption not in requestOptions
403	Not the post author (inbox / accept-reject)
404	Post or request not found
409	Already accepted, editing prompt after first request, or intake PAUSED/COMPLETED (§15.13)
429	Per-requester rate limit (100 submissions / rolling 24h)

15.12 — Snapshot freeze

Once the first PostRequest row exists for a post, the author cannot edit requestPrompt, requestPromptDescription, or requestOptions — server returns 409. This keeps every responder's selectedOptions stable against the chip catalog they actually saw. To "change the question", post a new one (or pause / complete the old one — see §15.13).

15.13 — Author: pause / resume / complete request intake

The author of a CTA-enabled post controls whether it accepts new requests. This never touches existing requests — a paused or completed post keeps all its PostRequest rows, and the author can still accept/reject anything already PENDING (§15.7).

PATCH /api/posts/:id/request-state
{ "action": "pause" }     // "pause" | "resume" | "complete"

• pause — stop accepting new requests (reversible).
• resume — reopen a paused post.
• complete — permanently close intake. Terminal — cannot be undone.

State machine (requestState on the post object):

action	from OPEN	from PAUSED	from COMPLETED
pause	→ PAUSED	200 (no-op)	409 (terminal)
resume	200 (no-op)	→ OPEN	409 (terminal)
complete	→ COMPLETED	→ COMPLETED	200 (no-op)

Author-only. Returns the full refreshed post object (same shape as GET /api/posts/:id) so the client can re-render requestState + the resolved cta in one round-trip. No notifications fire on any of these transitions.

While a post is PAUSED or COMPLETED, POST /api/posts/:id/requests (§15.4) returns 409 — surface cta.pausedLabel / cta.completedLabel and disable the pill (cta.actionable === false) so the viewer never taps into a 409.

code	meaning
400	Post type has no request CTA (e.g. ANYTHING)
403	Not the post author
404	Post not found (or private + viewer not approved)
409	Post already COMPLETED — intake permanently closed

---

16 — Save / unsave (private bookmark)

Private bookmark — viewer-only. The post author is never notified, and the save count is never exposed to other viewers. Use this for the bookmark icon and the "Saved" tab.

16.1 — Endpoints

PUT  /api/posts/:id/save        body: { saved: boolean }   idempotent
GET  /api/posts/saved           paginated list of viewer's saved posts

16.2 — Set save state

PUT /api/posts/:id/save
Content-Type: application/json

{ "saved": true }       // or false to unsave

Idempotent. {saved: true} is a no-op if already saved; {saved: false} is a no-op if not saved. The client sends the desired state directly, so the server never has to reconstruct intent from arrival order.

Response:

{
  "success": true,
  "data": {
    "saved": true, // echoes the requested state
    "updatedAt": "2026-06-15T07:35:40.451Z",
  },
}

isSaved on every post object reflects the current viewer's save state.

16.3 — Optimistic UI (mandatory pattern — same as /like)

1. On tap — flip isSaved immediately in the client store. Record the new value as the desired state for this post.
2. Fire PUT /api/posts/:id/save with { saved: <desired> } in the background. No await on the UI thread.
3. On HTTP error — roll back the local state and surface a toast.
4. On feed refetch / detail screen open — trust the server's isSaved as source of truth.

16.4 — Race conditions

Same rules as /like (§8.2):

• Serialize per post — keep at most one in-flight save mutation per postId. Cancel the previous before issuing a new one.
• Track desired state + updatedAt — store the user's latest intended saved value client-side. After each response, only apply it if its updatedAt is strictly newer than the last applied response for that post.
• Idempotent retry on failure — safe to re-send the same body.

Rate-limited: 30 calls per 10s per user.

16.5 — Saved tab list

GET /api/posts/saved?limit=20&cursor=<base64>

Returns the viewer's saved posts, newest save first (not newest post first — a viewer may have saved an old post recently).

Response shape identical to other list endpoints (items[] + nextCursor). Each item is normally a full post object including isSaved: true and the standard _count.

Unavailable-post shells

A saved row never silently disappears. When the viewer can no longer access the post (author flipped private, post deleted, author hid it), the row is returned as a shell with only the post id and an unavailableReason:

{
  "items": [
    {
      "id": "pst_abc",
      "isUnavailable": true,
      "unavailableReason": "RESTRICTED",
    },
    {
      /* full normal post object */
      "id": "pst_xyz",
      "isSaved": true,
      "isUnavailable": false, // (absent / falsy on visible posts)
      // ...
    },
  ],
  "nextCursor": "...",
}

unavailableReason enum:

value	cause
RESTRICTED	Author flipped profile to private and viewer is not an approved follower
DELETED	Post was hard-deleted (cascade)
HIDDEN_BY_AUTHOR	isHidden=true (moderation / shadow-hide)

Render shells as a greyed-out card: "This post is no longer available." Tap → PUT /api/posts/:id/save with { saved: false } to remove the save.

Pass nextCursor back as ?cursor=... to fetch the next page. Stop when null. Cursor is opaque (base64url-encoded (PostSave.createdAt, id)).

16.6 — Mobile render rule

• Saved icon → post.isSaved ? <BookmarkFilled/> : <BookmarkOutline/>.
• "Saved" tab in profile → GET /api/posts/saved on mount + pull-to- refresh.
• Render shells as {isUnavailable: true} → greyed card with remove affordance.
• No count rendered anywhere — save count is private.
• No notification badge — save never triggers a notification.

16.7 — Errors

code	meaning
401	Missing or invalid Authorization header
404	Post not found
429	Rate limit (30 calls / 10s per user)

---

17 — Repost (one-tap, v2)

A repost is a regular Post row with type=REPOST, content="" and originalPostId set. Renders as "X reposted" + embedded original card. One per (viewer, original), DB-enforced — re-tapping returns 409.

v2: quote reposts ("with thoughts") were removed. The endpoint takes an empty body; any non-empty body is a 400. Historical quote rows (content!="") may still appear — render their content above the embedded original. See mobile-post-interactions-guide.md §2 for the full v2 contract including repostedBy.

The kind catalog (GET /api/posts/types) does not include REPOST — mobile picker never offers it. Reposts are created exclusively via POST /api/posts/:id/repost.

17.1 — Endpoints

POST   /api/posts/:id/repost          body: {} → new post object
DELETE /api/posts/:id/repost          undo repost
GET    /api/posts/:id/reposts         repost list

17.2 — Repost a post

POST /api/posts/:id/repost
{}                          // body MUST be empty

Response: full post object (same shape as POST /api/posts) with type=REPOST, originalPostId resolved to root, and the embedded original summary. Server collapses repost-of-a-repost chains — the new row always points at the root original, never another repost.

Errors:

code	reason
400	self-repost (can't repost your own post)
400	original is hidden
400	non-empty body (quotes not supported)
404	original not found
409	already reposted (treat as success)
429	rate limit (30 reposts / 10 min)

17.3 — Post-object additions (every list + detail endpoint)

{
  // ...existing fields...
  "originalPostId": "pst_root123",     // null on non-reposts
  "original": {                         // embedded; null when original was deleted
    "id": "pst_root123",
    "type": "FIND_TEAMMATES",
    "title": "Looking for a 4th for hackathon",
    "content": "Building a flashcard app...",
    "createdAt": "2026-06-10T12:00:00Z",
    "author": { "id": "usr_a", "username": "alice", "profile": { ... } },
    "media": [ /* same shape as top-level post.media */ ]
  },
  "isReposted": true,                   // viewer has reposted this root
  "viewerRepostId": "pst_myrepost1",    // viewer's own repost row id
  "repostedBy": {                       // mutual-follow attribution; null when none
    "users": [ { "id": "usr_c", "username": "charlie", "profile": { ... } } ],
    "mutualCount": 5                    // total MUTUAL reposters; public total = _count.reposts
  },
  "_count": { "likes": 3, "comments": 5, "requests": 0, "reposts": 12 }
}

repostedBy names only the viewer's mutuals (both follow each other), capped at 3 newest — "Reposted by Charlie, Dana and 3 others". Keyed on the root post, so original and repost cards agree.

Render rule:

Feed never contains type=REPOST cards — reposts boost the original into feeds and repostedBy credits them. REPOST cards appear only on profile lists and notification deep-links. Always interact via post.id.

• type === "REPOST" + originalPostId !== null → show "X reposted" hat at top of card. Legacy quote rows: render content above the embedded original card (empty content = no body, just the original card).
• type === "REPOST" + originalPostId === null → original was deleted. Render placeholder ("Original removed").
• type !== "REPOST" → standard render. _count.reposts is the number of times this post has been reposted; isReposted tells you if the viewer is one of them.

Like + comment buttons on a repost card act on the repost row (not the original). Tap on the embedded original card → navigate to that post's detail screen.

17.4 — Undo a repost

DELETE /api/posts/:id/repost

:id can be the original or any post in the same repost chain — server resolves to root. Returns 409 if the viewer has no repost row.

17.5 — Repost list

GET /api/posts/:id/reposts?limit=20&cursor=<base64>

Returns reposts of the root original, newest first (kind:"quote" = legacy rows only).

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "pst_repost1",
        "kind": "simple",                   // "simple" | "quote"
        "createdAt": "2026-06-15T07:00:00Z",
        "user": { "id": "usr_b", "username": "bob", "profile": { ... } },
        "contentPreview": ""                // empty for simple
      },
      {
        "id": "pst_repost2",
        "kind": "quote",
        "createdAt": "2026-06-15T06:30:00Z",
        "user": { ... },
        "contentPreview": "Loved this — exactly what I've been saying..."
      }
    ],
    "nextCursor": "eyJj..."
  }
}

17.6 — Notifications

type	recipient	trigger
repost	root post author	viewer simple-reposts
quote_repost	root post author	viewer quote-reposts
mention	mentioned user	quote-repost contains @x

Payload data.entityId → the repost id (tap-through lands on the repost card, not the original). data.originalPostId carries the root id when the client wants to navigate to the original instead.

17.7 — Mobile UX summary

1. User taps repost icon → bottom sheet: "Repost" | "Quote".
2A. SIMPLE  → POST /api/posts/:id/repost {}.
    Mobile: flip isReposted=true on the source card, bump _count.reposts.
2B. QUOTE   → open compose w/ embedded original.
    POST /api/posts/:id/repost { content: "my take" }.
    Mobile: same flag flip + push the new repost into the user's profile feed.
3. Feed render: type=REPOST → "X reposted" hat + embedded original.
4. Undo simple → DELETE /api/posts/:id/repost.
   Undo quote  → DELETE /api/posts/:repostId (standard post delete).

Optimistic UI optional but recommended — server response is fast enough to skip if you'd rather just await.

---

18 — Share (external / URL)

Share generates a tracked URL the viewer can paste anywhere (WhatsApp, Messages, copy-paste). Backend tracks each share for analytics + future attribution.

Status (2026-09-09): the URL is live and served — https://letsclustr.com/posts/<id>?ref=<code>. Opening it launches the app once the app claims the domain, and otherwise renders a download page. Everything about configuring that on each platform is in mobile-deep-links-guide.md; this section is only about getting the URL.

18.1 — Endpoints

POST /api/posts/:id/share              body: { channel? } → { url, shareCode, channel }
GET  /api/posts/:id/share/preview      → { title, description, imageUrl }

18.2 — Record a share + get URL

POST /api/posts/:id/share
Content-Type: application/json

{ "channel": "NATIVE" }

channel is one of: WHATSAPP | TWITTER | INSTAGRAM | FACEBOOK | COPY_LINK | CHAT | NATIVE | OTHER.

Default NATIVE. Use NATIVE when invoking the OS native share sheet — the OS hides which target the user actually picked, so you can't attribute more precisely. Use specific channels only when the user picks an in-app target you know about (e.g. CHAT for in-app conversation share, COPY_LINK for copy-button).

Response:

{
  "success": true,
  "data": {
    "url": "https://letsclustr.com/posts/019f45c6-…?ref=Ab12CdEf34",
    "shareCode": "Ab12CdEf34",
    "channel": "NATIVE",
  },
}

Errors:

code	reason
404	post not found or hidden
429	rate limit (60 calls / minute / user)

18.3 — Mobile flow

1. User taps share icon on a post.
2. Mobile: POST /api/posts/:id/share { channel: "NATIVE" }.
3. Server returns { url, shareCode }.
4. Mobile passes url to iOS UIActivityViewController / Android
   Intent.ACTION_SEND.
5. User picks WhatsApp / Messages / Copy / etc. URL goes out.
6. Recipient taps the link:
   - app installed + domain verified → OS routes the URL into the app;
     parse the postId and open the detail screen.
   - app not installed → browser opens the fallback page with
     App Store / Play Store buttons.

18.4 — Share-sheet preview prefill

GET /api/posts/:id/share/preview

Returns the OG-meta values mobile can prefill in the OS share sheet so the recipient sees a meaningful link preview even before the link is fetched.

{
  "success": true,
  "data": {
    "title": "Looking for a 4th for hackathon team", // or fallback
    "description": "Building a flashcard app. Need a designer or another dev...",
    "imageUrl": "https://storage.googleapis.com/…/abc.jpg", // first image, or null
  },
}

Title falls back to <username> on Clustr for ANYTHING-kind posts that have no title. These values are for the OS share sheet only — the web page the recipient lands on shows branded metadata and never the post itself.

18.5 — Share count on post

Every post object now carries _count.shares. Render alongside likes / comments / reposts:

"_count": { "likes": 3, "comments": 5, "requests": 0, "reposts": 12, "shares": 7 }

No per-viewer isShared flag — share is a transient action, not a persisted viewer state.

18.6 — In-app chat share (cleaner UX path)

Corrected: sending a post into a chat is not a URL share. There is a native MessageType.POST_SHARE — send { postId } to POST /api/chat/conversations/:id/messages and the card is resolved per-viewer on read. See mobile-post-share-guide.md. A PostShare row with channel: CHAT is still written, so it counts here too. The URL flow in this section is for external channels only.

18.7 — What is still outstanding

Step	Status
Domain + TLS (letsclustr.com)	done — Firebase Hosting
AASA + assetlinks.json	served, carrying placeholder identifiers
Fallback page	done
Mobile config (Associated Domains / intent-filter)	yours — deep-links guide §3
Identifiers (team id, bundle, package, fingerprints)	yours — deep-links guide §8
Click attribution (ShareClick)	deferred, nothing reads ref

Until the identifiers land, a tapped link opens the browser fallback page rather than the app. That is unconfigured, not broken.