list_versions

List the version history (git commits) for a Bridge Town project. When path is provided (e.g. model/revenue.py, README.md, data/seed.csv), only commits that touched that file are shown; omit path to list project-wide history. Each version includes the commit SHA, human-readable commit message (derived from the natural-language prompt used to create or update the file), author name, and date. Use diff to compare two versions. Pagination: the default limit is 20 (soft default, max 50). When the response includes a non-empty next_cursor, pass it back as the cursor argument to retrieve the next page. An empty next_cursor means you have reached the end of the history. Returns: project (str) — project name; path (str|null) — path filter applied; branch (str) — branch queried; versions (list[{sha, short_sha, message, author, date}]) — commit entries; count (int) — entries in this page; next_cursor (str) — SHA to pass as cursor for the next page, empty when done.

read-only · idempotent

Parameters

Name	Type	Required	Default	Description
project_name	str	Yes	—
path	str	No	''
branch	str	No	'main'
limit	int	No	20
cursor	str	No	''

Returns

Returns a structured object. Top-level fields:

• project (string)
• branch (string)
• model_name (string)
• versions (array<object>)
• count (integer)
• next_cursor (string)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "list_versions",
  "arguments": {
    "project_name": "forecasts",
    "model_name": "revenue",
    "branch": "main",
    "limit": 5
  }
}

Response

{
  "project": "forecasts",
  "branch": "main",
  "model_name": "revenue",
  "versions": [
    {
      "sha": "abc1234def5678901234567890abcdef12345678",
      "short_sha": "abc1234",
      "author": "alice@example.com",
      "message": "tweak: bump growth assumption",
      "date": "2026-04-28T10:00:00+00:00"
    },
    {
      "sha": "0123456789abcdef0123456789abcdef01234567",
      "short_sha": "0123456",
      "author": "bob@example.com",
      "message": "feat: add revenue model",
      "date": "2026-04-27T18:00:00+00:00"
    }
  ],
  "count": 2,
  "next_cursor": ""
}

Notes

• Module: Versions
• Requires authentication via API token or Auth0 JWT.