Versioning
The version is in the path: https://dash.alethman.com/api/v1. Version 1 is the only version and is stable.
What can change within v1
Section titled “What can change within v1”Additions only. Build your client to tolerate them:
- New fields in a response object. Ignore fields you do not know; do not fail on them.
- New endpoints, and new optional parameters on existing ones.
- New values in an open list: a new
event_type, sector, attribution kind, report section or alert kind. Handle a value you do not recognise as “other” rather than failing. - New error messages. The
codeof an existing error never changes; themessagemay be reworded. - New MCP tools, and new optional arguments on existing tools.
What never changes within v1
Section titled “What never changes within v1”- A field’s name, type or meaning, and whether it can be null.
- A parameter’s name, meaning, range or default.
- An error’s status and
code. - The shape of a list (
data,next_cursor) and of an error (error.code,error.message). - The scopes an endpoint needs.
- The
content.versionof a report: a report’s content changes format only under a newcontent.version, and old reports keep the version they were compiled with.
A breaking change
Section titled “A breaking change”If something must break, it ships as a new version (/api/v2) beside v1, and v1 keeps answering while you move. Workspace owners hear about it before v1 is retired. Every change, breaking or not, lands in the Changelog.
Readings change; shapes do not
Section titled “Readings change; shapes do not”Alethman tunes how it reads the news: how stories are grouped, how risk is read, how findings are graded. A story’s risk_score today may differ from what the same story would have scored last month. That is a change in the reading, not in the API: the field, its 0 to 100 range and its meaning stay the same. When the meaning of a field would change, that is a new field.