> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Changelog

> Release history for the REST API.

All notable changes to this project will be documented in this file.

The format is based on [Common Changelog](https://common-changelog.org/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## \[0.46.0] - 2026-08-13

### Removed

* **Breaking:** Remove the Mesa Git Server API. Users can no longer use vanilla Git clients with Mesa. Our first-class Git sync feature continues to function as usual.
* **Breaking:** Remove the Mesa MCP server

### Fixed

* Fix a bug causing older MesaFS FUSE clients to fail when using private-key-signed access tokens

## \[0.45.0] - 2026-08-11

### Changed

* Stop recording API-key usage during authentication

### Removed

* Remove stale last-triggered values from webhook target views

### Fixed

* Fix gRPC not-found responses interrupting unrelated VCS requests on shared HTTP/2 sessions
* Fix HTTP/2 stream resets crashing API workers under concurrent VCS traffic
* Fix canceled VCS requests creating excess HTTP/2 sessions and stalled streams
* Fix VCS request stalls after task replacement by draining watch streams and replacing stale HTTP/2 sessions
* Fix API-key usage updates blocking authenticated requests under concurrency
* Fix concurrent writes returning internal errors instead of retrying transaction conflicts
* Fix VCS request stalls when long-lived watch streams exhaust shared HTTP/2 connections

## \[0.44.1] - 2026-08-09

### Changed

* Re-shape VCS `ApplyOps` streams at the gateway to the server-advertised operation and message-size limits, including requests from older clients

### Added

* Add the maximum encoded request-message size to the existing VCS `ApplyOps` policy response

### Fixed

* Replace VCS upstream HTTP/2 connections after `ENHANCE_YOUR_CALM` resets and spread requests across four long-lived connections

## \[0.44.0] - 2026-08-07

### Changed

* Limit signing-key commit attribution to 100 ordered authors
* Name `allow_backwards` rather than the CLI-only flag spelling in the `BOOKMARK_MOVE_HISTORY_REWRITE` message
* Allow Git sync to move rewritten branches and tags with exact old-OID leases
* Allow Git pushes to move rewritten branches and tags with exact old-OID leases
* Add a bounded online command to repair stale and same-Change physical ancestry
* Keep lightweight and annotated Git tags attached when their target Change commits are rewritten and omit invalid signatures from rewritten tag objects
* Rebase descendant Changes recursively when a parent Change evolves, preserving committed content and bookmark positions while rejecting descendants with pending writes

### Added

* Add transparent pagination for Content API directory listings
* Report the refused bookmarks in `details.bookmark_names` on `BOOKMARK_MOVE_HISTORY_REWRITE` errors
* Use signing-key authors for Mesa commit writes and preserve Git authors and co-authors during pushes and sync

### Fixed

* Fix Git sync rewrite races and partial branch/tag updates with atomic leased retries
* Fix clean ancestor bookmark merges that hang during conflict checks
* Fix duplicate changes across paginated merge histories with tied or nonmonotonic commit times

## \[0.43.0] - 2026-08-02

### Changed

* **Breaking:** Require REST and MCP bookmark moves to advance history unless `allow_backwards` is set
* Add atomic multi-bookmark moves to the VCS service

### Added

* Support private-key-signed tokens for Mesa Git Server APIs and MCP

### Fixed

* Fix webhooks not firing for repository mutations made through the Mesa CLI or MesaFS
* Retry transient webhook delivery failures
* Prevent VCS object reads from returning blob or tree content not registered to the requested repository
* Prevent `SetChangeBase` from overwriting a change that evolved while its new commit was being computed

## \[0.42.0] - 2026-07-16

### Added

* Add dashboard management for organization signing keys, including browser-local key generation, two-key rotation, revocation, and last-used activity

### Fixed

* Fix the GET change RPC to report `files` and `updated_at` correctly

## \[0.40.0] - 2026-07-12

### Changed

* **Breaking:** Align repository names with GitHub's naming rules — a single path segment of letters, numbers, periods, hyphens, and underscores. Slash-separated (nested) names are no longer accepted, and `.`, `..`, and names ending in `.git` are rejected. Periods are newly allowed (e.g. `.dotfiles`, `sdk-v1.2`)
* **Breaking:** Make repository names case-insensitively unique per organization — names keep the casing they were created with, but `MyRepo` and `myrepo` now refer to the same repository and can no longer coexist

## \[0.39.0] - 2026-07-08

### Changed

* **Breaking:** Reserve tag keys starting with `$` for filter operators — creating or updating repository or API key tags with a `$`-prefixed key now returns `INVALID_REQUEST`

### Added

* Add structured JSON tag filters to `GET /v1/:org/repos`, with `$`-prefixed case-insensitive operators (`$and`, `$or`, `$not`, `$eq`, `$in`, `$contains`, `$starts_with`, `$ends_with`, `$exists`) and case-insensitive tag matching

### Deprecated

* Deprecate legacy comma-separated repo tag filters in favor of structured JSON tag filters

## \[0.37.0] - 2026-06-17

### Added

* Include a `trace_id` field in 5xx error responses. Quote it when reporting an issue and Mesa support can pull up the exact failing request.

## \[0.36.0] - 2026-06-09

### Added

* Accept access tokens (JWTs) as Bearer credentials on all v1 REST endpoints and the VCS gateway, anywhere an API key is accepted. Tokens are signed locally from an API key, with no token endpoint to call. Each request re-verifies the token against its signing key and clamps its scopes and repository access to the key's current state, so disabling or revoking the key invalidates every token it signed

## \[0.35.0] - 2026-06-07

### Added

* Add the Mesa MCP server, which lets you connect your coding agents and other AI tools to Mesa. Through it, an agent can:
  * Create repositories, and list or look up existing ones
  * Browse directories, read file contents, and inspect path metadata at any change or commit
  * Inspect commit and change history, including a change's full evolution, and diff any two changes or commits
  * Create a change, write, edit, or delete files in it, then snapshot the result into durable history
  * List, create, move, delete, and merge bookmarks to publish work
  * Add `https://api.mesa.dev/mcp` as a custom connector, sign in, and choose what access to grant to use the MCP server

### Fixed

* Change writes that hit a concurrent modification now return `409 Conflict` instead of `500`.

## \[0.34.0] - 2026-06-01

### Added

* Add shallow clone and partial clone support for Git fetch over protocol v2, including `--depth`, `--deepen`, `--unshallow`, `--filter=blob:none`, `--filter=blob:limit=<n>`, and `--filter=tree:0`.
* Add `ref-in-want` support for Git fetch over protocol v2, allowing clients to request refs directly during fetch.

## \[0.33.0] - 2026-05-26

### Changed

* **Breaking:** Git fetch (`git-upload-pack`) now speaks **Git protocol v2 only**. `info/refs?service=git-upload-pack` always returns a v2 capability advertisement (`version 2`, `ls-refs=unborn peel`, `fetch=wait-for-done`, `object-format=sha1`, etc.); `POST /git-upload-pack` accepts `command=ls-refs` and `command=fetch` request framing. Pre-v2 Git clients can no longer fetch from Mesa — minimum supported client is **Git 2.18** (≥ 2.26 strongly recommended, since 2.26 enables v2 by default). Push (`git-receive-pack`) is unchanged. The `Git-Protocol` request header is now intentionally ignored on the upload-pack route.
* Change responses now report parent change IDs instead of commit SHAs of prior versions of the same change.

## \[0.31.0] - 2026-05-21

### Changed

* **Breaking:** Rename the content-metadata surface from `xattrs` to `metadata`. `GET /v1/:org/:repo/content` responses now expose a `metadata` object instead of `xattrs`; directory listings filter via repeatable `metadata[<key>]=<value>` deepObject params instead of `xattr=<name>:<value>`; and keys are bare (the `user.mesa.*` namespace prefix is dropped).

## \[0.30.0] - 2026-05-19

### Added

* Add optional `xattrs` metadata to `GET /v1/:org/:repo/content` responses. Files, symlinks, directories, and directory entries now include UTF-8 string extended attributes under `user.mesa.*` when present.
* Add repeatable `xattr=<name>:<value>` filters to `GET /v1/:org/:repo/content` directory listings, returning entries that match all supplied xattr filters.

### Changed

* Change `POST /v1/:org/:repo/changes` and `PATCH /v1/:org/:repo/changes/:change_id` message handling so omitted `message` creates a change with no description on POST and preserves the existing description on PATCH, while explicit string values are accepted including `""` to clear a description.
* Change `POST /v1/:org/:repo/bookmarks/merge` to accept an optional `message`; omitted `message` uses a generated merge description, while explicit string values are accepted including `""` for no description.

## \[0.29.2] - 2026-05-17

### Added

* Add `GET /v1/:org/:repo/bookmarks/:bookmark` for direct bookmark lookup by name, and add `glob` filtering to `GET /v1/:org/:repo/bookmarks`
* Add optional `ref_globs` filters to `POST /v1/:org/:repo/upstream/syncs`. Omit it to sync all supported branches and tags, or pass branch/tag glob strings such as `{ "branches": "main" }`

## \[0.29.0] - 2026-05-15

### Added

* Add `upstream` field to repository responses (`{ url, auth_kind, latest_sync } | null`). Upstreams are added, replaced, or removed via `POST /v1/:org/repos` and `PATCH /v1/:org/:repo`. Auth is write-only: pass `{ kind: 'token', token, token_username? }` or `{ kind: 'username_password', username, password }`; responses expose only `auth_kind`
* Add `POST /v1/:org/:repo/upstream/syncs` to enqueue a sync with the repository upstream. Pass `{ "direction": "pull" }` or `{ "direction": "push" }`. Returns the `sync` row; the worker processes it asynchronously. Read `upstream.latest_sync`, call `GET /v1/:org/:repo/upstream/syncs/:syncId`, list `GET /v1/:org/:repo/upstream/syncs`, or subscribe to `sync.{queued,in_progress,completed,failed}` webhooks
* Add `GET /v1/:org/:repo/upstream/syncs` and `GET /v1/:org/:repo/upstream/syncs/:syncId` for repository upstream sync history
* Add `sync.queued`, `sync.in_progress`, `sync.completed`, and `sync.failed` webhook event types covering the lifecycle of a sync

### Changed

* Change webhook delivery `User-Agent` from `Depot-Webhook/1.0` to `Mesa-Webhook/1.0`

### Removed

* Remove deprecated `X-Depot-Event`, `X-Depot-Delivery`, and `X-Depot-Signature` webhook delivery headers

### Fixed

* Empty repos created via `POST /:org/repos` are now usable by mesa clients without manual seeding — the server lazily materializes an initial change on first write, advancing the default bookmark off `ZERO_OID` at the same time. `git push` to a fresh repo continues to work as a ref-create without `--force` ([MES-1387](https://linear.app/mesa-dev/issue/MES-1387))

## \[0.28.2] - 2026-05-07

### Changed

* Hide refs that point at (or descend from) an unresolved conflict from `git fetch` and `git ls-remote`. These refs previously failed mid-fetch

## \[0.28.1] - 2026-05-06

### Added

* Add `X-Mesa-Event`, `X-Mesa-Delivery`, and `X-Mesa-Signature` webhook delivery headers alongside existing `X-Depot-*` headers

### Changed

* Rename raw-content response headers `X-Depot-Blob-Hash` and `X-Depot-Blob-Size` to `X-Mesa-Blob-Hash` and `X-Mesa-Blob-Size`
* Deprecate `X-Depot-Event`, `X-Depot-Delivery`, and `X-Depot-Signature` webhook delivery headers. Receivers must migrate to the `X-Mesa-*` equivalents by 2026-05-11 or signature verification will fail when the legacy headers stop being sent

## \[0.28.0] - 2026-05-03

### Fixed

* Return 409 Conflict instead of 500 Internal Server Error on concurrent bookmark writes.

## \[0.27.0] - 2026-04-30

No user-facing changes.

## \[0.26.0] - 2026-04-29

### Added

* Add webhook management endpoints for creating, updating, and deleting repository webhooks.
* Add git tag support in receive-pack, info/refs, and upload-pack.