roadmap-audiences

roadmap_audiences is the per-workspace list of who a Work item may be shown to on a roadmap. Every workspace starts with Leadership, Customers and Investors, and can rename, recolour, reorder, delete or add to them in Settings → Roadmap Audiences.

Like work-item types, it is workspace configuration, not a Golden Thread entity. A Work item lists its audiences in features.roadmap_audience_ids.

Tagging Work

roadmap_audience_ids is a uuid[] on features. Send the whole list on PATCH /api/v1/features/{id}; [] clears it. Every id must be an audience in the same workspace, or the write is refused with 422 and the missing ids. Duplicates are dropped.

An empty list means Internal Only: the in-app roadmap still shows the item, but no audience view, share link or public roadmap does. New Work starts Internal Only.

Deleting an audience removes it from every Work item that carried it.

What an audience sees

An audience sees a Work item when both hold:

1. The item is tagged with the audience.
2. The item's effort is at least the audience's min_effort (xs to xl). null means any size. An item with no effort always passes: the tag is the deliberate choice, the size only trims noise.

The work-item type's show_on_roadmap still applies first, everywhere. Outside viewers also only see items that are Planned, In Progress (In Review and Testing count as In Progress) or Shipped, not drafts and not the trash.

The public roadmap

With roadmap audiences on, the public roadmap (GET /api/v1/public/roadmap/{slug} and /embed/{slug}/roadmap) lists only items that a public audience (is_public: true) sees. Customers is seeded public.

Private share links

An audience can have one private link, /share/roadmap/{token}, that shows its roadmap to anyone holding it, without signing in. Links are made, replaced and revoked by owners and admins, in Settings or with:

• POST /api/roadmap-audiences/{id}/share makes a link, or replaces the current one. The old link stops working at once.
• DELETE /api/roadmap-audiences/{id}/share revokes it.

Both answer { "data": { "share_token": "…" } } (null after a revoke). The generic PATCH cannot set share_token. Share pages carry noindex and send no referrer.

Fields

Permissions

Any workspace member reads audiences and tags Work with them. Members and above create and edit audiences; deleting one needs admin or owner.