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

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);
}

from pierre import Pierre

# The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
pierre = Pierre()

for metadata in pierre.repos.files.metadata.list(
    repo_name="my-demo-repository",
    ephemeral=True,
    limit=200,
    path="docs",
    recursive=True,
    ref="main",
):
    print(metadata)

import (
	"context"
	"fmt"

	pierre "github.com/pierrecomputer/sdk/go"
)

ctx := context.Background()
// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
client, err := pierre.NewClient()
if err != nil {
	return err
}
page, err := client.Repos.Files.Metadata.List(ctx, pierre.ReposFilesMetadataListParams{
	RepoName:  "my-demo-repository",
	Ephemeral: pierre.Bool(true),
	Limit:     pierre.Int(200),
	Path:      pierre.String("docs"),
	Recursive: pierre.Bool(true),
	Ref:       pierre.String("main"),
})
if err != nil {
	return err
}
for metadata, err := range page.All(ctx) {
	if err != nil {
		return err
	}
	fmt.Println(metadata)
}

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

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

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.

Scopes

git:read

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

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"

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);
}

from pierre import Pierre

# The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
pierre = Pierre()

for metadata in pierre.repos.files.metadata.list(
    repo_name="my-demo-repository",
    ephemeral=True,
    limit=200,
    path="docs",
    recursive=True,
    ref="main",
):
    print(metadata)

import (
	"context"
	"fmt"

	pierre "github.com/pierrecomputer/sdk/go"
)

ctx := context.Background()
// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
client, err := pierre.NewClient()
if err != nil {
	return err
}
page, err := client.Repos.Files.Metadata.List(ctx, pierre.ReposFilesMetadataListParams{
	RepoName:  "my-demo-repository",
	Ephemeral: pierre.Bool(true),
	Limit:     pierre.Int(200),
	Path:      pierre.String("docs"),
	Recursive: pierre.Bool(true),
	Ref:       pierre.String("main"),
})
if err != nil {
	return err
}
for metadata, err := range page.All(ctx) {
	if err != nil {
		return err
	}
	fmt.Println(metadata)
}

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

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

Getting Started

Platform

Workflows

Libraries

API Reference

repos.files.metadata.list

Authorizations

Scopes

Path Parameters

Query Parameters

Response