If you've built a custom theme or done anything programmatic with your archive pages, you've probably had to reverse-engineer the data that Buttondown passes to your templates. What fields are available? What types are they? What's nested where? The answer has mostly been "check the docs and hope for the best."

Now there's a proper OpenAPI spec describing the full shape of the template context — every field, every type, every nested object. It covers everything from newsletter metadata and email content to subscriber details and subscription URLs.

This matters if you're building on top of Buttondown's archives. If you're writing custom CSS themes, building integrations, or just want autocomplete in your editor, having a machine-readable schema makes all of that easier. And if you're not doing any of that — this doesn't change anything for you, your archives work exactly the same.

We're publishing this for the same reason we've been investing in archives more broadly this year. Between new themes, more customization options, and the larger archives overhaul we outlined at the start of the year, we've been making a lot of changes to how archives work. A formal spec is our way of being transparent about what the contract looks like — and being deliberate about not breaking it. If we change the shape of the data your templates rely on, we want that to be a conscious, documented decision, not an accident.