Siren is a hypermedia specification for representing entities in JSON, including their properties, actions, and links. It enables clients to discover available state transitions and operations dynamically from API responses.
Siren
Siren is a hypermedia specification, created by Kevin Swiber, for representing entities in JSON along with their properties, the actions that can be taken on them, and the links that connect them to related entities. Where plain JSON returns only data, Siren returns data plus the affordances — so a client can discover what it is allowed to do next straight from the response.
- Entities - The core construct: a thing with
class,properties, and nested sub-entities. - Actions - Named, executable operations complete with HTTP method, target URL, and expected fields, so state transitions are described in the payload.
- Links - Typed relationships to related resources that let a client navigate the API without hardcoding URLs.
- Class-based semantics - A
classarray conveys the nature of an entity or action, giving generic clients a hook for behavior.
Siren sits alongside HAL, JSON:API, and Collection+JSON in the family of hypermedia formats that tried to make REST APIs self-describing. It never reached mass adoption, but its action-first design reads as prescient in the agentic era: an interface that ships its own executable affordances is exactly what an autonomous client needs to act safely without a human hardcoding every call. It is a useful reference point when thinking about how APIs describe not just their data but what can be done with it.
Referenced on the API Evangelist blog
Where this standard shows up across sixteen years of my writing at apievangelist.com — how it fits into API design, governance, and the agentic turn.
