# File Operations

The Forgejo API provides endpoints for reading, creating, updating, and deleting files in repositories, as well as accessing raw content and archives.

## Endpoint Overview

### File CRUD (Contents API)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/repos/{owner}/{repo}/contents` | List root directory |
| `GET` | `/repos/{owner}/{repo}/contents/{filepath}` | Get file content (base64 encoded) |
| `POST` | `/repos/{owner}/{repo}/contents/{filepath}` | Create a new file |
| `PUT` | `/repos/{owner}/{repo}/contents/{filepath}` | Update an existing file |
| `DELETE` | `/repos/{owner}/{repo}/contents/{filepath}` | Delete a file |
| `POST` | `/repos/{owner}/{repo}/contents` | Create/update multiple files in one commit |
| `POST` | `/repos/{owner}/{repo}/diffpatch` | Apply a diff/patch |

See [crud.md](crud.md) for full details, request/response schemas, and examples.

### Raw and Media Content

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/repos/{owner}/{repo}/raw/{filepath}` | Get raw file content (no encoding) |
| `GET` | `/repos/{owner}/{repo}/media/{filepath}` | Get media file content |
| `GET` | `/repos/{owner}/{repo}/editorconfig/{filepath}` | Get .editorconfig rules for a file |
| `GET` | `/repos/{owner}/{repo}/archive/{archive}` | Download repository archive |
| `GET` | `/repos/{owner}/{repo}/compare/{basehead}` | Compare two refs |

See [raw-media.md](raw-media.md) for full details and examples.

## Key Concepts

- **Base64 encoding**: The contents API returns file content base64-encoded and expects base64-encoded content when creating/updating files
- **SHA requirement**: Update and delete operations require the current file SHA to prevent conflicts (optimistic locking)
- **Branch targeting**: All write operations can target a specific branch or create a new branch
- **Ref parameter**: GET operations accept a `ref` query parameter to read from a specific branch, tag, or commit
