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.

read-only · idempotent

Parameters

Name	Type	Required	Default	Description
project_name	Annotated[str, Field(description='Name of the Bridge Town project.')]	Yes	—
path	Annotated[str, Field(description="Project-relative file path (e.g. 'model/revenue.py'). Omit to operate on the whole project.")]	No	''
branch	Annotated[str, Field(description="Branch to inspect. Defaults to the project's default branch.")]	No	'main'
limit	Annotated[int, Field(description='Maximum number of commits to return. Defaults to 20.')]	No	20
cursor	Annotated[str, Field(description='Pagination cursor from a previous list_versions response to fetch the next page.')]	No	''

Returns

Returns a structured object. Top-level fields:

• project (string)
• path (null)
• branch (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",
  "path": null,
  "branch": "main",
  "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.