Following up on subscriber-editable tags: when subscribers see a list of tags they can toggle on or off, sometimes the tag name alone doesn't tell the whole story. "Weekly" is clear enough, but "Premium Content" or "Beta Access" might need a bit more context.

Now you can add a public_description to any tag. This shows up as helper text in the subscriber portal, right below the tag name — giving subscribers the context they need to make an informed choice.

The new field is available in the Tags API:

curl -X POST https://api.buttondown.com/v1/tags \
  -H "Authorization: Token $API_KEY" \
  -d name="Beta Access" \
  -d public_description="Get early access to new features before they're released to everyone." \
  -d subscriber_editable=true

You can also add it when updating existing tags:

curl -X PATCH https://api.buttondown.com/v1/tags/{id} \
  -H "Authorization: Token $API_KEY" \
  -d public_description="Weekly digest of the best links from the community."

The field is optional and only matters for subscriber-editable tags — if a tag isn't visible in the portal, the description won't show anywhere. But for tags that are subscriber-facing, a good description can make the difference between someone toggling it on or scrolling past.