Social guides
Guides

Tagging people in posts.

Tag actors when you create or edit a post. Each tag lands as pending — the tagged actor approves it before it shows on their profile, or removes it if they don't want it. Approved tags surface on a visibility- and block-aware /tagged listing, and every new tag fires a tag notification and a tag.created webhook.

1

Tag on create (or PATCH)

Pass tags — an array of actor UUIDs — on post create or PATCH. Each becomes a pending tag. Silently skipped: yourself, ids that aren't active actors in the community, and any actor with a block in either direction with the author. Max 30 per call. On PATCH, tags are additive — existing approved/removed tags are never reset, and re-tagging someone is a no-op.

bash
curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "Content-Type: application/json" \
  -d '{
        "actor_id": "<author>",
        "body": "Great shoot with the crew!",
        "tags": ["<bob>", "<carol>"]
      }' \
  "https://social.productcraft.co/v1/communities/<c>/posts"

2

Approve or remove

The tagged actor approves their own tag (only they can — anyone else gets a 403). Either the tagged actor or the post author can remove it. Both are verb routes carrying the acting actor in the body, and both return 201 with the tag row — read state (pending / approved / removed) to confirm. Both are idempotent; approving an already-removed tag is a 409.

bash
# Bob accepts being tagged
curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "actor_id": "<bob>" }' \
  "https://social.productcraft.co/v1/communities/<c>/posts/<post>/tags/<bob>/approve"

# Bob (or the post author) removes the tag
curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "actor_id": "<bob>" }' \
  "https://social.productcraft.co/v1/communities/<c>/posts/<post>/tags/<bob>/remove"

3

The /tagged listing

An actor's approved tags, on published + unexpired posts, newest-tag-first. Pass the viewer via requester_id so followers / close-friends posts they're allowed to read surface; without it only public posts appear, and posts by authors who block (or are blocked by) the viewer are dropped.

Cursor-paginated (limit default 50, max 200) with the usual { next_cursor, has_more } envelope. Pages can come back shorter than limit because visibility is filtered after the page boundary — follow next_cursor until has_more is false rather than until a page looks short.

bash
curl -H "Authorization: Bearer pcft_live_..." \
  "https://social.productcraft.co/v1/communities/<c>/actors/<bob>/tagged?requester_id=<viewer>&limit=20"

4

Notifications & webhooks

  • Each new tag fires a tag notification to the tagged actor (respecting their per-kind notification preference — they can mute tag like any other kind).
  • Each new tag also emits a tag.created webhook event (subscribe via the webhooks API) carrying the post, author, and tagged actor.
  • Blocked pairs can never tag each other — enforced server-side, so you don't filter it client-side.