# Settings & Admin API

## Public Settings

### API Settings

```
GET /api/v1/settings/api
```

Returns API-level configuration.

```bash
curl -s "${FORGEJO_URL}/api/v1/settings/api" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

**Response:**

```json
{
  "max_response_items": 50,
  "default_paging_num": 30,
  "default_git_trees_per_page": 1000,
  "default_max_blob_size": 10485760
}
```

---

### Attachment Settings

```
GET /api/v1/settings/attachment
```

```bash
curl -s "${FORGEJO_URL}/api/v1/settings/attachment" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

**Response:**

```json
{
  "enabled": true,
  "allowed_types": ".csv,.docx,.fodg,.fodp,.fods,.fodt,.gif,.gz,.jpeg,.jpg,.log,.md,.mov,.mp4,.odf,.odg,.odp,.ods,.odt,.patch,.pdf,.png,.pptx,.svg,.tgz,.txt,.webm,.xls,.xlsx,.zip",
  "max_size": 4,
  "max_files": 5
}
```

---

### Repository Settings

```
GET /api/v1/settings/repository
```

```bash
curl -s "${FORGEJO_URL}/api/v1/settings/repository" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

**Response:**

```json
{
  "mirrors_disabled": false,
  "http_git_disabled": false,
  "migrations_disabled": false,
  "stars_disabled": false,
  "time_tracking_disabled": false,
  "lfs_disabled": false
}
```

---

### UI Settings

```
GET /api/v1/settings/ui
```

```bash
curl -s "${FORGEJO_URL}/api/v1/settings/ui" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

**Response:**

```json
{
  "default_theme": "forgejo-auto",
  "allowed_reactions": ["+1", "-1", "laugh", "hooray", "confused", "heart", "rocket", "eyes"],
  "custom_emojis": ["codeberg", "forgejo"]
}
```

---

## Admin Endpoints

All admin endpoints require admin privileges.

### Cron Tasks

#### List Cron Tasks

```
GET /api/v1/admin/cron
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/cron" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Run Cron Task

```
POST /api/v1/admin/cron/{task}
```

```bash
# Run repo stats update
curl -s -X POST "${FORGEJO_URL}/api/v1/admin/cron/update_mirrors" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Run garbage collection
curl -s -X POST "${FORGEJO_URL}/api/v1/admin/cron/repo_health_check" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Email Management

#### List All Emails

```
GET /api/v1/admin/emails
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/emails?page=1&limit=50" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Search Emails

```
GET /api/v1/admin/emails/search
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/emails/search?q={domain}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Organization Management

#### List All Organizations

```
GET /api/v1/admin/orgs
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/orgs?page=1&limit=50" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### User Management

#### List All Users

```
GET /api/v1/admin/users
```

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `source_id` | integer | Filter by login source ID |
| `page` | integer | Page number (1-based) |
| `limit` | integer | Page size |

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/users?page=1&limit=50" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Filter by login source
curl -s "${FORGEJO_URL}/api/v1/admin/users?source_id={source_id}&page=1&limit=50" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Create User

```
POST /api/v1/admin/users
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/admin/users" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "{username}",
    "email": "{email}",
    "password": "{password}",
    "must_change_password": true,
    "login_name": "{username}",
    "send_notify": false,
    "visibility": "public"
  }'
```

#### Edit User

```
PATCH /api/v1/admin/users/{username}
```

```bash
# Change user email
curl -s -X PATCH "${FORGEJO_URL}/api/v1/admin/users/{username}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"email": "newemail@example.com"}'

# Promote to admin
curl -s -X PATCH "${FORGEJO_URL}/api/v1/admin/users/{username}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"is_admin": true}'

# Disable user
curl -s -X PATCH "${FORGEJO_URL}/api/v1/admin/users/{username}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"active": false, "prohibit_login": true}'
```

#### Delete User

```
DELETE /api/v1/admin/users/{username}
```

```bash
# Delete user (will fail if user owns repos)
curl -s -X DELETE "${FORGEJO_URL}/api/v1/admin/users/{username}" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Purge user and all their data
curl -s -X DELETE "${FORGEJO_URL}/api/v1/admin/users/{username}?purge=true" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Get User Emails

```
GET /api/v1/admin/users/{username}/emails
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/users/{username}/emails" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Delete User Email

```
DELETE /api/v1/admin/users/{username}/emails
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/admin/users/{username}/emails" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["old@example.com"]}'
```

---

### SSH Key Management

#### Add SSH Key for User

```
POST /api/v1/admin/users/{username}/keys
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/admin/users/{username}/keys" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "work-laptop",
    "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG... user@host"
  }'
```

#### Delete SSH Key

```
DELETE /api/v1/admin/users/{username}/keys/{id}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/admin/users/{username}/keys/{key_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Admin Create Operations

#### Create Org for User

```
POST /api/v1/admin/users/{username}/orgs
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/admin/users/{username}/orgs" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "new-org",
    "full_name": "New Organization",
    "description": "An organization created by admin",
    "visibility": "public"
  }'
```

#### Create Repo for User

```
POST /api/v1/admin/users/{username}/repos
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/admin/users/{username}/repos" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "{repo}",
    "description": "Repository created by admin",
    "private": false,
    "auto_init": true
  }'
```

#### Rename User

```
POST /api/v1/admin/users/{username}/rename
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/admin/users/{username}/rename" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"new_username": "newname"}'
```

---

### Unadopted Repositories

Manage repositories on disk that are not tracked by Forgejo.

#### List Unadopted Repos

```
GET /api/v1/admin/unadopted
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/unadopted?page=1&limit=50" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Adopt Repository

```
POST /api/v1/admin/unadopted/{owner}/{repo}
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/admin/unadopted/{owner}/{repo}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Delete Unadopted Repository

```
DELETE /api/v1/admin/unadopted/{owner}/{repo}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/admin/unadopted/{owner}/{repo}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Admin Quota Endpoints

### Quota Groups

#### List Quota Groups

```
GET /api/v1/admin/quota/groups
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/quota/groups" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Create Quota Group

```
POST /api/v1/admin/quota/groups
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/admin/quota/groups" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "{quota_group}",
    "rules": []
  }'
```

#### Get Quota Group

```
GET /api/v1/admin/quota/groups/{quotagroup}
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/quota/groups/{quota_group}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Delete Quota Group

```
DELETE /api/v1/admin/quota/groups/{quotagroup}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/admin/quota/groups/{quota_group}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Add Rule to Group

```
PUT /api/v1/admin/quota/groups/{quotagroup}/rules/{quotarule}
```

```bash
curl -s -X PUT "${FORGEJO_URL}/api/v1/admin/quota/groups/{quota_group}/rules/{quota_rule}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Remove Rule from Group

```
DELETE /api/v1/admin/quota/groups/{quotagroup}/rules/{quotarule}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/admin/quota/groups/{quota_group}/rules/{quota_rule}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### List Users in Quota Group

```
GET /api/v1/admin/quota/groups/{quotagroup}/users
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/quota/groups/{quota_group}/users" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Add User to Quota Group

```
PUT /api/v1/admin/quota/groups/{quotagroup}/users/{username}
```

```bash
curl -s -X PUT "${FORGEJO_URL}/api/v1/admin/quota/groups/{quota_group}/users/{username}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Remove User from Quota Group

```
DELETE /api/v1/admin/quota/groups/{quotagroup}/users/{username}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/admin/quota/groups/{quota_group}/users/{username}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Quota Rules

#### List Quota Rules

```
GET /api/v1/admin/quota/rules
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/quota/rules" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Create Quota Rule

```
POST /api/v1/admin/quota/rules
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/admin/quota/rules" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "{quota_rule}",
    "limit": 1073741824,
    "subjects": ["size:repos:all"]
  }'
```

#### Get Quota Rule

```
GET /api/v1/admin/quota/rules/{quotarule}
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/quota/rules/{quota_rule}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Edit Quota Rule

```
PATCH /api/v1/admin/quota/rules/{quotarule}
```

```bash
curl -s -X PATCH "${FORGEJO_URL}/api/v1/admin/quota/rules/{quota_rule}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"limit": 2147483648}'
```

#### Delete Quota Rule

```
DELETE /api/v1/admin/quota/rules/{quotarule}
```

```bash
curl -s -X DELETE "${FORGEJO_URL}/api/v1/admin/quota/rules/{quota_rule}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## User Quota

### Get User Quota (Admin)

```
GET /api/v1/admin/users/{username}/quota
```

```bash
curl -s "${FORGEJO_URL}/api/v1/admin/users/{username}/quota" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Add Quota Group to User (Admin)

```
POST /api/v1/admin/users/{username}/quota/groups
```

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/admin/users/{username}/quota/groups" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"groups": ["{quota_group}"]}'
```

### Current User Quota

```
GET /api/v1/user/quota
```

```bash
curl -s "${FORGEJO_URL}/api/v1/user/quota" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Quota Usage Details

```bash
# Artifacts usage
curl -s "${FORGEJO_URL}/api/v1/user/quota/artifacts" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Attachments usage
curl -s "${FORGEJO_URL}/api/v1/user/quota/attachments" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Check if action is allowed by quota
curl -s "${FORGEJO_URL}/api/v1/user/quota/check" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Packages usage
curl -s "${FORGEJO_URL}/api/v1/user/quota/packages" \
  -H "Authorization: token ${FORGEJO_PAT}"
```
