Files

Copy MarkdownOpen

List Directory

GET /v1/repos/:slug/tree/:ref/*path
GET /v1/repos/:namespace/:slug/tree/:ref/*path

The :ref can be a branch name, tag, or commit SHA.

Query Parameters

Response 200:

{
  "items": [
    { "name": "src", "path": "src", "type": "folder", "sha": "a1c2...", "mode": "040000" },
    { "name": "README.md", "path": "README.md", "type": "file", "sha": "7f3b...", "mode": "100644" }
  ],
  "path": "",
  "ref": "main",
  "sha": "d4e5...",
  "truncated": false
}

Entry types are "folder" or "file". When recursive=true, all entries from all subdirectories are returned in a flat list with full relative paths. If the repository contains more than 10,000 entries, truncated will be true.

Supports ETag / If-None-Match for caching. When the ref is a commit SHA, responses include Cache-Control: immutable.

Read File

GET /v1/repos/:slug/blob/:ref/*path
GET /v1/repos/:namespace/:slug/blob/:ref/*path

Returns the file content. Binary files are returned as base64. Max file size: 50 MB (lifted when Range is set — see below).

Response 200:

{
  "content": "# Hello World\n",
  "encoding": "utf-8",
  "path": "README.md",
  "sha": "7f3b...",
  "size": 15
}

Supports ETag / If-None-Match for caching. Sets Accept-Ranges: bytes so clients can probe range support.

Range Reads

Send an HTTP Range: bytes=N-M (or bytes=N- for "to end") header to fetch a slice. Inclusive byte offsets, RFC 7233 semantics. The 50 MB cap is bypassed when Range is present — useful for streaming logs, model weights, or any large asset in chunks.

GET /v1/repos/:slug/blob/main/big.parquet
Range: bytes=0-1048575

Response 206 Partial Content:

{
  "content": "<base64 of bytes 0-1048575>",
  "encoding": "base64",
  "path": "big.parquet",
  "sha": "ab12...",
  "size": 5242880,
  "range": { "start": 0, "end": 1048575, "length": 1048576 }
}

Headers: Content-Range: bytes 0-1048575/5242880, Vary: Range. Returns 416 with Content-Range: bytes */<size> for an out-of-range request.

Read Multiple Files (Batch)

POST /v1/repos/:slug/blobs/batch
POST /v1/repos/:namespace/:slug/blobs/batch

Read up to 100 files in one round-trip. Reuses the same edge-cached flat-tree path as /blob, so the cost is one ref-resolve plus N parallel storage reads (server chunks at 25 to fit the Worker subrequest budget). Use this from MountedFS.readFiles() to collapse N readFile RTTs into one.

Body:

{
  "ref": "main",
  "paths": ["README.md", "src/a.ts", "src/b.ts"],
  "encoding": "auto",
  "max_size": 52428800
}

Response 200:

{
  "blobs": [
    { "path": "README.md", "sha": "f6b1...", "size": 20, "encoding": "utf-8", "content": "# ...\n" },
    { "path": "src/a.ts",  "sha": "cc79...", "size": 20, "encoding": "utf-8", "content": "..." }
  ],
  "missing": ["nonexistent.md"]
}

ETag is W/"batch-<hash>" derived from the sorted SHA list of resolved blobs — clients can short-circuit a repeat batch with If-None-Match.

Stream Raw Bytes

GET /v1/repos/:slug/raw/:ref/*path
GET /v1/repos/:namespace/:slug/raw/:ref/*path

Streaming sibling of /blob/. Returns raw bytes (no JSON envelope, no base64 inflation). Content-Type is sniffed: text/plain; charset=utf-8 for text, application/octet-stream for binary. Honors the same Range header as /blob/.

Response 200:

HTTP/2 200
Content-Type: text/plain; charset=utf-8
Content-Length: 20
ETag: "cc79..."
X-Content-Sha: cc79...
Accept-Ranges: bytes

export const a = 1;

The X-Content-Sha header carries the git blob SHA so clients can cache by content. Use this for large files where the JSON+base64 overhead of /blob matters (~33 % savings on binary, plus no client-side base64 decode).

List Refs

GET /v1/repos/:slug/refs
GET /v1/repos/:namespace/:slug/refs

Returns all branches and tags with their head SHAs:

{
  "branches": [
    { "name": "main", "sha": "7f3b...", "type": "branch" }
  ],
  "tags": [
    { "name": "v1.0", "sha": "a1c2...", "type": "tag" }
  ],
  "default_branch": "main",
  "total": 2,
  "next_cursor": null
}