# User and Organization Quota API Reference

Quota endpoints allow users to check their resource usage and admins to manage quota rules and groups.

**Note:** Quota may not be configured on all instances. If quotas are disabled, these endpoints may return empty results or 404.

---

## User Quota Endpoints

### Get Quota Information

```
GET /user/quota
```

Returns the authenticated user's quota usage and limits.

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

**QuotaInfo Response Object:**

| Field  | Type          | Description                        |
|--------|---------------|------------------------------------|
| used   | QuotaUsed     | Current resource usage             |
| groups | array[QuotaGroup] | Quota groups assigned to user  |

**QuotaUsed fields:**

| Field                  | Type    | Description                     |
|------------------------|---------|---------------------------------|
| size.repos.public      | integer | Bytes used by public repos      |
| size.repos.private     | integer | Bytes used by private repos     |
| size.git.LFS           | integer | Bytes used by Git LFS           |
| size.assets.releases   | integer | Bytes used by release assets    |
| size.assets.artifacts  | integer | Bytes used by CI artifacts      |
| size.assets.packages   | integer | Bytes used by packages          |
| size.assets.attachments| integer | Bytes used by attachments       |

### List Artifacts Affecting Quota

```
GET /user/quota/artifacts
```

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

### List Attachments Affecting Quota

```
GET /user/quota/attachments
```

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

### List Packages Affecting Quota

```
GET /user/quota/packages
```

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

### Check if Over Quota

```
GET /user/quota/check
```

**Query Parameters:**

| Parameter | Type   | Description                                                |
|-----------|--------|------------------------------------------------------------|
| subject   | string | Quota subject to check (e.g., `size:repos:all`, `size:git:LFS`, `size:assets:all`) |

Returns `200` with a boolean result.

```bash
# Check if over total repo quota
curl -s "${FORGEJO_URL}/api/v1/user/quota/check?subject=size:repos:all" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Check if over LFS quota
curl -s "${FORGEJO_URL}/api/v1/user/quota/check?subject=size:git:LFS" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Check if over package quota
curl -s "${FORGEJO_URL}/api/v1/user/quota/check?subject=size:assets:packages" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Organization Quota Endpoints

Same structure as user endpoints, scoped to an organization:

| Endpoint                           | Description                     |
|------------------------------------|---------------------------------|
| `GET /orgs/{org}/quota`            | Get org quota info              |
| `GET /orgs/{org}/quota/artifacts`  | List org artifacts              |
| `GET /orgs/{org}/quota/attachments`| List org attachments            |
| `GET /orgs/{org}/quota/packages`   | List org packages               |
| `GET /orgs/{org}/quota/check`      | Check if org is over quota      |

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

# Check org quota
curl -s "${FORGEJO_URL}/api/v1/orgs/{org}/quota/check?subject=size:repos:all" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Admin Quota Management

These endpoints require **site admin** privileges.

### Get a User's Quota (Admin)

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

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

### Set Quota Groups for a User

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

**JSON Body:**

| Field  | Type          | Description                            |
|--------|---------------|----------------------------------------|
| groups | array[string] | Quota group names to assign to user    |

```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": ["default", "premium"]}'
```

---

### Quota Rules

Quota rules define limits on specific resource subjects.

**QuotaRule fields:**

| Field    | Type          | Description                                                    |
|----------|---------------|----------------------------------------------------------------|
| name     | string        | Rule name (unique identifier)                                  |
| limit    | integer       | Limit in bytes (0 = no usage allowed, -1 = unlimited)          |
| subjects | array[string] | Resource subjects this rule applies to (e.g., `size:repos:all`) |

**Available subjects:**

| Subject                 | Description                    |
|-------------------------|--------------------------------|
| `size:repos:public`     | Public repository size         |
| `size:repos:private`    | Private repository size        |
| `size:repos:all`        | All repository size            |
| `size:git:LFS`          | Git LFS storage                |
| `size:git:all`          | All git storage                |
| `size:assets:releases`  | Release asset storage          |
| `size:assets:artifacts` | CI artifact storage            |
| `size:assets:packages`  | Package registry storage       |
| `size:assets:attachments`| Issue/PR attachment storage   |
| `size:assets:all`       | All asset storage              |
| `size:all`              | Total storage across all types |

#### List All Rules

```
GET /admin/quota/rules
```

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

#### Create a Rule

```
POST /admin/quota/rules
```

```bash
# Create a 5 GB repo limit rule
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": 5368709120,
    "subjects": ["size:repos:all"]
  }'

# Create a 1 GB LFS limit rule
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:git:LFS"]
  }'

# Create an unlimited rule
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": -1,
    "subjects": ["size:repos:all"]
  }'
```

#### Get / Update / Delete a Rule

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

# Update a rule (PATCH)
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": 10737418240}'

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

---

### Quota Groups

Quota groups bundle multiple rules together and are assigned to users.

**QuotaGroup fields:**

| Field | Type             | Description                          |
|-------|------------------|--------------------------------------|
| name  | string           | Group name (unique identifier)       |
| rules | array[QuotaRule]  | Rules in this group                  |

#### List All Groups

```
GET /admin/quota/groups
```

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

#### Create a Group

```
POST /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}"}'
```

#### Get / Delete a Group

```bash
# Get group details (includes rules and users)
curl -s "${FORGEJO_URL}/api/v1/admin/quota/groups/{quota_group}" \
  -H "Authorization: token ${FORGEJO_PAT}"

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

#### Manage Users in a Group

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

# Add a user to a group
curl -s -X PUT "${FORGEJO_URL}/api/v1/admin/quota/groups/{quota_group}/users/{username}" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Remove a user from a group
curl -s -X DELETE "${FORGEJO_URL}/api/v1/admin/quota/groups/{quota_group}/users/{username}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

#### Manage Rules in a Group

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

# Remove a rule from a group
curl -s -X DELETE "${FORGEJO_URL}/api/v1/admin/quota/groups/{quota_group}/rules/{quota_rule}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Common Patterns

### Check if User is Near Quota

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

# Extract usage (adjust field paths based on actual response structure)
REPO_USED=$(echo "$QUOTA" | jq '.used.size.repos.public + .used.size.repos.private')

# Get limit from the first group's rules (simplified)
REPO_LIMIT=$(echo "$QUOTA" | jq '[.groups[].rules[] | select(.subjects[] == "size:repos:all") | .limit] | max')

if [ "$REPO_LIMIT" != "null" ] && [ "$REPO_LIMIT" != "-1" ] && [ "$REPO_LIMIT" -gt 0 ]; then
  PERCENT=$(( REPO_USED * 100 / REPO_LIMIT ))
  echo "Repo usage: ${REPO_USED} / ${REPO_LIMIT} bytes (${PERCENT}%)"
  
  if [ "$PERCENT" -ge 90 ]; then
    echo "WARNING: Over 90% of repo quota used!"
  elif [ "$PERCENT" -ge 75 ]; then
    echo "NOTICE: Over 75% of repo quota used."
  fi
else
  echo "No repo quota limit set or unlimited."
fi
```

### Full Admin Setup: Create Tier with Rules

```bash
# 1. Create 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": 2147483648, "subjects": ["size:repos:all"]}'

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": 524288000, "subjects": ["size:git:LFS"]}'

# 2. Create group
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}"}'

# 3. Add rules to group
curl -s -X PUT "${FORGEJO_URL}/api/v1/admin/quota/groups/{quota_group}/rules/{quota_rule}" \
  -H "Authorization: token ${FORGEJO_PAT}"

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

# 4. Assign users to group
for USER in {user1} {user2} {user3}; do
  curl -s -X PUT "${FORGEJO_URL}/api/v1/admin/quota/groups/{quota_group}/users/${USER}" \
    -H "Authorization: token ${FORGEJO_PAT}"
done

echo "Free tier quota configured."
```
