Skip to content

Versioning

The version is in the path: https://dash.alethman.com/api/v1. Version 1 is the only version and is stable.

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 code of an existing error never changes; the message may be reworded.
  • New MCP tools, and new optional arguments on existing tools.
  • 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.version of a report: a report’s content changes format only under a new content.version, and old reports keep the version they were compiled with.

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.

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.