repos.files.metadata.list

Return a recursive file tree together with per-file commit metadata in one request. Each file also includes a derived type field for symmetry with /files.

The server reads the last commit of each file under path, also when the call sends a limit or a cursor. When those files have more than 50,000 distinct last commits, the call fails with a 429 response, and a retry gets the same response. To list such a tree, send a narrower path.

Scope: git:read on the repository.

GET /api/repos/{repo_name}/files/metadata

TypeScript

TypeScript

import { Pierre } from '@pierre/sdk';

// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
const pierre = new Pierre();

for await (const metadata of pierre.repos.files.metadata.list({
  repo_name: 'my-demo-repository',
  ephemeral: true,
  limit: 200,
  path: 'docs',
  recursive: true,
  ref: 'main',
})) {
  console.log(metadata);
}

200

{
  "files": [
    {
      "last_commit_sha": "a1b2c3d4e5f6",
      "mode": "100644",
      "path": "README.md",
      "size": 2048,
      "type": "blob"
    }
  ],
  "has_more": true,
  "next_cursor": "MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY",
  "ref": "main"
}

Authorizations

Authorization · string · header · required

JWT bearer token signed with your organization's registered signing key. There is no OAuth authorization server; you mint tokens yourself and the token's scopes claim carries the granted permission scopes. Public scopes: git:read (read repository contents), git:write (write branches, commits, tags, and notes), repo:write (create and manage repositories), org:read (list an organization's repositories). Each operation's security requirement names the scopes it requires. See https://code.storage/docs/getting-started/authentication for how to mint tokens.

Path Parameters

repo_name · string · required

The repository name, for example acme/web.

Query Parameters

ref · string

Optional branch, tag, or commit SHA to list from. When omitted, the repository default branch is used.

path · string

Optional repository-relative subtree to list recursively. Empty means the repository root.

recursive · boolean

Accepted for API symmetry. Metadata listings are recursive regardless of this flag.

cursor · string

Pagination cursor returned by a previous list_files_with_metadata response.

limit · integer

Maximum number of files to return. A call with no limit and no cursor returns every file in one response, with has_more false. A limit of 0 is the same as no limit. A call with a cursor and no limit returns up to 200 files.

Required range: 0 <= x <= 1000

ephemeral · boolean

Whether ref should be resolved from the ephemeral namespace.

Response

200

application/json

The repository tree plus deduplicated commit metadata for the latest change touching each file.

Files in the repository at the resolved revision, each annotated with mode, type, and the latest commit that changed it.

commits · object · required

Commit metadata keyed by last_commit_sha so repeated commits are only sent once.

Show child attributes

files · object[] · required

Files in the resolved revision, each annotated with the latest commit that changed it.

Show child attributes

has_more · boolean · required

Whether another page is available.

Example:

true

ref · string · required

The resolved ref or commit used to generate the listing.

Example:

"main"

next_cursor · string

Opaque cursor for the next page. Pass it as cursor to read the next page. Absent when there are no more results.

Example:

"MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY"