repos.files.list

GET

api

repos

{repo_name}

files

TypeScript

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

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

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

from pierre import Pierre

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

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

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.List(ctx, pierre.ReposFilesListParams{
	RepoName:  "my-demo-repository",
	Ephemeral: pierre.Bool(true),
	Limit:     pierre.Int(1000),
	Path:      pierre.String("docs"),
	Ref:       pierre.String("main"),
})
if err != nil {
	return err
}
for file, err := range page.All(ctx) {
	if err != nil {
		return err
	}
	fmt.Println(file)
}

{
  "entries": [
    {
      "mode": "100644",
      "path": "src/main.go",
      "type": "blob"
    }
  ],
  "has_more": true,
  "next_cursor": "MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY",
  "paths": [
    "README.md"
  ],
  "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. Empty means the repository root.

recursive

boolean

default:true

When true, include descendants recursively. When false, only direct children are returned. Defaults to true.

cursor

string

Pagination cursor returned by a previous list_files response.

limit

integer

Maximum number of paths to return. A call with no limit and no cursor returns every path 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 1000 paths.

Required range: 0 <= x <= 5000

ephemeral

boolean

Whether ref should be resolved from the ephemeral namespace.

Response

Tree entries for the resolved revision.

Paginated tree entries in the repository at the resolved revision.

entries

object[]

required

Tree entries for the resolved revision.

Show child attributes

has_more

boolean

required

Whether another page is available.

Example:

true

paths

string[]

required

Flat blob-only path list. Mirrors the path of every entry whose type is "blob". Convenience shape for callers that just want file paths; use entries when you need type/mode.

Repository-relative path used to scope the operation.

Example:

["README.md"]

ref

string

required

The resolved reference (branch name or commit SHA) that was used.

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 file of pierre.repos.files.list({
  repo_name: 'my-demo-repository',
  ephemeral: true,
  limit: 1000,
  path: 'docs',
  ref: 'main',
})) {
  console.log(file);
}

from pierre import Pierre

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

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

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.List(ctx, pierre.ReposFilesListParams{
	RepoName:  "my-demo-repository",
	Ephemeral: pierre.Bool(true),
	Limit:     pierre.Int(1000),
	Path:      pierre.String("docs"),
	Ref:       pierre.String("main"),
})
if err != nil {
	return err
}
for file, err := range page.All(ctx) {
	if err != nil {
		return err
	}
	fmt.Println(file)
}

{
  "entries": [
    {
      "mode": "100644",
      "path": "src/main.go",
      "type": "blob"
    }
  ],
  "has_more": true,
  "next_cursor": "MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY",
  "paths": [
    "README.md"
  ],
  "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

Authorizations

Scopes

Path Parameters

Query Parameters

Response