# Repository, Organization, and User Avatars API Reference

Manage avatars (profile images) for repositories, organizations, and users via the API.

---

## Repository Avatar Endpoints

### Set Repository Avatar

```
POST /repos/{owner}/{repo}/avatar
```

**Path Parameters:**

| Parameter | Type   | Required | Description        |
|-----------|--------|----------|--------------------|
| owner     | string | yes      | Repository owner   |
| repo      | string | yes      | Repository name    |

**JSON Body:**

| Field | Type   | Required | Description                                    |
|-------|--------|----------|------------------------------------------------|
| image | string | yes      | Base64-encoded image data (PNG, JPEG, or GIF)  |

**Response:** `204 No Content` on success.

```bash
# Set repository avatar from a local file
IMAGE_BASE64=$(base64 -w 0 < avatar.png)
curl -s -o /dev/null -w "%{http_code}" -X POST \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/avatar" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d "{\"image\": \"${IMAGE_BASE64}\"}"
# Expect: 204
```

### Delete Repository Avatar

```
DELETE /repos/{owner}/{repo}/avatar
```

Reverts the repository to its default generated avatar.

**Response:** `204 No Content` on success.

```bash
curl -s -o /dev/null -w "%{http_code}" -X DELETE \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/avatar" \
  -H "Authorization: token ${FORGEJO_PAT}"
# Expect: 204
```

---

## All Avatar Endpoints

| Entity       | Set (POST)                       | Delete (DELETE)                  |
|--------------|----------------------------------|----------------------------------|
| Repository   | `/repos/{owner}/{repo}/avatar`   | `/repos/{owner}/{repo}/avatar`   |
| Organization | `/orgs/{org}/avatar`             | `/orgs/{org}/avatar`             |
| User         | `/user/avatar`                   | `/user/avatar`                   |

All three use the same JSON body format: `{"image": "<base64-encoded data>"}`.
All return **204 No Content** on success for both set and delete operations.

---

## Request Body Format

The `image` field must contain **base64-encoded** image data. The image should be:

- **Formats:** PNG, JPEG, or GIF
- **Recommended size:** Square images work best. Forgejo will resize/crop as needed, but providing a square image (e.g., 256x256 or 512x512) avoids unexpected cropping.
- **Max size:** Subject to server configuration. Very large images may be rejected. Keep images under 1 MB for best results.
- **No data URI prefix:** Send raw base64, not a data URI (no `data:image/png;base64,` prefix).

---

## Examples

### Encode From a Local File

```bash
# PNG file
IMAGE_BASE64=$(base64 -w 0 < /path/to/avatar.png)

# JPEG file
IMAGE_BASE64=$(base64 -w 0 < /path/to/photo.jpg)

# Set as repo avatar
curl -s -o /dev/null -w "%{http_code}" -X POST \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/avatar" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d "{\"image\": \"${IMAGE_BASE64}\"}"
```

### Download From URL and Set as Avatar

```bash
# Download an image and base64-encode it in one step
IMAGE_BASE64=$(curl -sL "https://example.com/logo.png" | base64 -w 0)

# Set as org avatar
curl -s -o /dev/null -w "%{http_code}" -X POST \
  "${FORGEJO_URL}/api/v1/orgs/{org}/avatar" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d "{\"image\": \"${IMAGE_BASE64}\"}"
```

### Set User Avatar

```bash
IMAGE_BASE64=$(base64 -w 0 < my-profile-pic.png)
curl -s -o /dev/null -w "%{http_code}" -X POST \
  "${FORGEJO_URL}/api/v1/user/avatar" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d "{\"image\": \"${IMAGE_BASE64}\"}"
```

### Delete User Avatar

```bash
curl -s -o /dev/null -w "%{http_code}" -X DELETE \
  "${FORGEJO_URL}/api/v1/user/avatar" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Response Codes

| Code | Meaning                                          |
|------|--------------------------------------------------|
| 204  | Success (avatar set or deleted)                  |
| 400  | Bad request (invalid base64, unsupported format) |
| 401  | Authentication required                          |
| 403  | Permission denied (not owner/admin)              |
| 404  | Repository/org/user not found                    |
