# File Contents API reference

Base: `https://git.mpm.to/api/v1`

All file content responses encode the file body as base64 in the `content` field. Decode with:
```bash
echo "BASE64STRING" | base64 -d
```

## Get a file or directory listing

```bash
curl -s -H "Authorization: token e82a7235b948fbbeea60329422fcac89fa5a5ce8" \
  "https://git.mpm.to/api/v1/repos/{owner}/{repo}/contents/{filepath}?ref=main"
```

`ref` can be a branch name, tag, or commit SHA (defaults to the default branch if omitted). `filepath` is the path within the repo, e.g. `src/main.go` or `docs/`.

If `filepath` is a directory, the response is an array of file entries with `name`, `path`, `type` (`file` | `dir` | `symlink`), `size`, and `sha`.

If `filepath` is a file, the response includes `content` (base64-encoded), `encoding`, `sha`, `size`, `name`, `path`, `html_url`.

## Read a file and decode it

```bash
SHA=$(curl -s -H "Authorization: token e82a7235b948fbbeea60329422fcac89fa5a5ce8" \
  "https://git.mpm.to/api/v1/repos/{owner}/{repo}/contents/{filepath}" \
  | python3 -c "import sys,json; r=json.load(sys.stdin); print(r['sha'])")

curl -s -H "Authorization: token e82a7235b948fbbeea60329422fcac89fa5a5ce8" \
  "https://git.mpm.to/api/v1/repos/{owner}/{repo}/contents/{filepath}" \
  | python3 -c "import sys,json,base64; r=json.load(sys.stdin); print(base64.b64decode(r['content']).decode())"
```

## Create a new file

```bash
CONTENT_B64=$(echo -n "file content here" | base64)

curl -s -X POST \
  -H "Authorization: token e82a7235b948fbbeea60329422fcac89fa5a5ce8" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"Add new file\",
    \"content\": \"${CONTENT_B64}\",
    \"branch\": \"main\"
  }" \
  "https://git.mpm.to/api/v1/repos/{owner}/{repo}/contents/{filepath}"
```

## Update an existing file

Updating requires the current file's `sha`. Fetch it first, then:

```bash
# Step 1: get the sha
SHA=$(curl -s -H "Authorization: token e82a7235b948fbbeea60329422fcac89fa5a5ce8" \
  "https://git.mpm.to/api/v1/repos/{owner}/{repo}/contents/{filepath}" \
  | python3 -c "import sys,json; r=json.load(sys.stdin); print(r['sha'])")

# Step 2: base64-encode the new content
NEW_CONTENT=$(echo -n "new file content" | base64)

# Step 3: update
curl -s -X PUT \
  -H "Authorization: token e82a7235b948fbbeea60329422fcac89fa5a5ce8" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"Update file\",
    \"content\": \"${NEW_CONTENT}\",
    \"sha\": \"${SHA}\",
    \"branch\": \"main\"
  }" \
  "https://git.mpm.to/api/v1/repos/{owner}/{repo}/contents/{filepath}"
```

## Delete a file

```bash
SHA=$(curl -s -H "Authorization: token e82a7235b948fbbeea60329422fcac89fa5a5ce8" \
  "https://git.mpm.to/api/v1/repos/{owner}/{repo}/contents/{filepath}" \
  | python3 -c "import sys,json; r=json.load(sys.stdin); print(r['sha'])")

curl -s -X DELETE \
  -H "Authorization: token e82a7235b948fbbeea60329422fcac89fa5a5ce8" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"Delete file\",
    \"sha\": \"${SHA}\",
    \"branch\": \"main\"
  }" \
  "https://git.mpm.to/api/v1/repos/{owner}/{repo}/contents/{filepath}"
```

Always confirm with the user before deleting a file.

## Get raw file content (no base64)

```bash
curl -s -H "Authorization: token e82a7235b948fbbeea60329422fcac89fa5a5ce8" \
  "https://git.mpm.to/api/v1/repos/{owner}/{repo}/raw/{filepath}?ref=main"
```

This returns the raw file bytes directly — useful for binary files or when you just want the content without decoding.

## Get a file at a specific commit/tag

Use `?ref=COMMIT_SHA` or `?ref=v1.2.0` as the query parameter.

## List commits for a file

```bash
curl -s -H "Authorization: token e82a7235b948fbbeea60329422fcac89fa5a5ce8" \
  "https://git.mpm.to/api/v1/repos/{owner}/{repo}/commits?path={filepath}&limit=20"
```

## Git trees (recursive directory listing)

```bash
curl -s -H "Authorization: token e82a7235b948fbbeea60329422fcac89fa5a5ce8" \
  "https://git.mpm.to/api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true"
```

Get `sha` from the branch info: `GET /repos/{owner}/{repo}/branches/{branch}` → `commit.commit.tree.sha`.