cleveragents-core/.opencode/skills/forgejo-api/references/settings-admin

Settings & Admin API

Public Settings

API Settings

GET /api/v1/settings/api

Returns API-level configuration.

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

Response:

{
  "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

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

Response:

{
  "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

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

Response:

{
  "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

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

Response:

{
  "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

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

Run Cron Task

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

# 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

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

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

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

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

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}

# 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}

# 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

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

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

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}

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

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

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

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

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}

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}

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

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

Create Quota Group

POST /api/v1/admin/quota/groups

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}

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}

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}

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}

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

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}

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}

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

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

Create Quota Rule

POST /api/v1/admin/quota/rules

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}

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}

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}

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

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

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

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

Quota Usage Details

# 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}"