List Files with Metadata

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.

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

List Files with Metadata

cURL

curl --request GET \
  --url https://api.{cluster}.code.storage/api/repos/{repo_name}/files/metadata \
  --header 'Authorization: Bearer <token>'

200

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

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

repo_name · string · required

Repository name. Names that contain / or any other character that is not safe in a URL path segment must be URL encoded so the value occupies a single path segment. For example pierre/example is sent as pierre%2Fexample. Plain names such as example can be sent as-is. The server URL-decodes the value before resolving the repository.

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 · default: 200

Maximum number of files to return. Defaults to 200.

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 of files is available.

Example:

true

ref · string · required

The resolved ref or commit used to generate the listing.

Example:

"main"

next_cursor · string

Cursor to resume pagination from. Empty when there are no more results.

Example:

"docs/guide.md"