Skip to main content
Returns every file in the repository at a given ref, along with per-file git metadata and a deduplicated index of the commits that last touched each file. 
GET /api/v1/repos/files/metadata?ref=BRANCH_OR_SHA
Authorization: Bearer YOUR_JWT_TOKEN

​
Parameters

​
ref
string
Branch name or commit SHA to resolve the file tree against. If omitted, the server falls back to the repository’s default_branch, then HEAD, then main.
​
ephemeral
boolean
When true, branch refs are resolved under the ephemeral namespace before lookup. This changes ref resolution behavior — it is not a filter. Passing ephemeral=true without a valid ref that maps to an ephemeral branch returns a 400. Any value other than true or false is also a 400.

​
JWT Requirements

  • The JWT must include the repository in the repo claim — the repo is not inferred from the URL
  • Requires git:read scope

​
Response

{
  "files": [
    {
      "path": "README.md",
      "mode": "100644",
      "size": 12,
      "last_commit_sha": "deadbeef"
    },
    {
      "path": "src/index.js",
      "mode": "100644",
      "size": 4096,
      "last_commit_sha": "deadbeef"
    }
  ],
  "commits": {
    "deadbeef": {
      "author": "Jane Doe",
      "date": "2026-02-19T12:00:00Z",
      "message": "initial commit"
    }
  },
  "ref": "main"
}

​
Response fields

files[] — one entry per file in the tree at the resolved ref.
FieldTypeDescription
pathstringFile path relative to the repository root
modestringGit file mode (e.g. 100644 for a regular file, 100755 for executable)
sizenumberFile size in bytes
last_commit_shastringSHA of the most recent commit that modified this file
commits — a map of commit SHA → commit metadata. Each SHA that appears in files[].last_commit_sha has a corresponding entry here. The map is deduplicated: if many files share the same last-touching commit, that commit appears once.
FieldTypeDescription
authorstringCommit author name
datestringCommit timestamp in RFC 3339 / ISO 8601 format
messagestringFull commit message
ref — the ref the server actually resolved and used, regardless of what was passed in the query string.

​
Pagination

This endpoint is unpaginated. The full file list is returned in a single response — there are no cursor, next_cursor, limit, or has_more fields. For large repositories this can produce a significant payload. If your repo has tens of thousands of files or a high rate of unique last-touching commits, account for response size in your client and consider caching the result on your side.

​
Error Responses

​
400 Bad Request
string
Invalid ephemeral value (anything other than true/false), or ephemeral=true used with a ref that cannot be resolved in the ephemeral namespace.
​
401 Unauthorized
string
JWT is missing or invalid.
​
403 Forbidden
string
JWT is valid but does not carry git:read scope.
​
404 Not Found
string
Repository not found, or the specified ref (branch or SHA) does not exist.
​
405 Method Not Allowed
string
Request was made with a method other than GET.
​
408 Request Timeout
string
Request was canceled while the server was preparing the repository.
​
429 Too Many Requests
string
The repository has too many unique last-touching commit SHAs to expand into the commits map. Contact support.
​
503 Service Unavailable
string
Repository is thawing or syncing, a replica could not be selected, or storage is temporarily unavailable. Retry with backoff.
​
500 Internal Server Error
string
Unexpected server-side failure.
All error responses use JSON: {"error": "<message>"}.