Fetch files

If you want a directory listing or a few file bytes without a Git clone, GET /v1/repos/{user}/{repo}/contents. Directories return JSON. Files return the raw bytes. Content-Type is guessed from the file name. This is not Git. Clone, fetch, and push still use Git over HTTPS.

Needs grant API_COMMITS_READ or ALL. The same grant lists branches and commits. Send Authorization: Bearer. See Authentication and Grants.

The Amendable browse UI (/r/.../blob/... and /r/.../raw/...) is the account owner’s website session. Agents and backends should call this API, not scrape HTML.

List a directory

Omit the path, or pass a directory, to get a tree. Root path is the empty string.

curl

curl -sS \
  "https://api.amendable.io/v1/repos/$AMENDABLE_USERNAME/$AMENDABLE_REPO/contents" \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"

curl -sS \
  "https://api.amendable.io/v1/repos/$AMENDABLE_USERNAME/$AMENDABLE_REPO/contents/src" \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"

Python

# pip install httpx
import os
import httpx

user = os.environ["AMENDABLE_USERNAME"]
repo = os.environ["AMENDABLE_REPO"]
r = httpx.get(
    f"https://api.amendable.io/v1/repos/{user}/{repo}/contents",
    headers={"Authorization": f"Bearer {os.environ['AMENDABLE_TOKEN']}"},
)
r.raise_for_status()
print(r.json())

Response (200), Content-Type: application/json:

{
  "type": "tree",
  "path": "",
  "hexsha": "4b825dc642cb6eb9a060e54bf8d69288fbee4904",
  "entries": [
    {
      "type": "blob",
      "name": "hello.txt",
      "path": "hello.txt",
      "hexsha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "mode": 33188,
      "size": 12,
      "mime_type": "text/plain"
    },
    {
      "type": "tree",
      "name": "src",
      "path": "src",
      "hexsha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "mode": 16384
    }
  ]
}

mode is the Git file mode as a decimal integer (33188 is a regular file 100644, 16384 is a directory 040000). Blob entries include size and mime_type. Tree entries do not. Directory listings include files larger than the download cap. Fetching those files is 403. See Size cap.

Fetch a file

A file path returns the object bytes. Content-Type is guessed from the file name (hello.txt is text/plain). Unknown names are text/plain. The body is the file bytes, not Base64.

curl

curl -sS \
  "https://api.amendable.io/v1/repos/$AMENDABLE_USERNAME/$AMENDABLE_REPO/contents/hello.txt" \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"

Python

# pip install httpx
import os
import httpx

user = os.environ["AMENDABLE_USERNAME"]
repo = os.environ["AMENDABLE_REPO"]
r = httpx.get(
    f"https://api.amendable.io/v1/repos/{user}/{repo}/contents/hello.txt",
    headers={"Authorization": f"Bearer {os.environ['AMENDABLE_TOKEN']}"},
)
r.raise_for_status()
print(r.headers["X-Amendable-Git-Type"])
print(r.content)

A .json file is still a blob. The body is the file bytes, and Content-Type is application/json. Read X-Amendable-Git-Type first so you do not treat that file as a directory listing.

Headers

Every 200 includes:

Header	Meaning
X-Amendable-Git-Type	tree (directory JSON) or blob (file bytes)
X-Amendable-Git-Hexsha	Git object id
X-Amendable-Git-Size	Blob size in bytes. Files only.

Choose a ref

ref is a branch name or a 40-character commit hexsha. Omit it to use the repository default branch.

curl -sS \
  "https://api.amendable.io/v1/repos/$AMENDABLE_USERNAME/$AMENDABLE_REPO/contents?ref=main" \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"

curl -sS \
  "https://api.amendable.io/v1/repos/$AMENDABLE_USERNAME/$AMENDABLE_REPO/contents/hello.txt?ref=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"

Unknown ref is 404 No commit found in the repository. A repo with no commits is the same 404, matching GET /v1/repos/{user}/{repo}/commits.

Size cap

Files larger than 64 MiB return 403 Blob too large to fetch via the contents API (max 67108864 bytes) before Amendable reads the object. The directory listing still shows the entry and its size. Clone over Git HTTP for larger files.

Transfer

Response body bytes count as transfer (egress) for the current UTC month, the same quota as clone and fetch. Already over the hard cap is 403 on both directory listings and file downloads. See Usage and quotas.

Errors

Status	Typical cause
401	Missing Authorization: Bearer, unknown token, or missing API_COMMITS_READ
403	File larger than 64 MiB, or transfer quota exceeded
404	Unknown repo, unknown path, unknown ref, or no commit yet

Unknown path is Path not found. A path that walks through a file (README.md/nested) is also 404.

Request and response fields: HTTP reference.